ProtectHost White Mark II Programmer's Guide
Preface
Preface
© 2007 SafeNet, Inc. All rights reserved.
Part Number: 003198-002 (Rev D, 06/2007)
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
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: support@safenet-inc.com
© SafeNet, Inc.
i
ProtectHost White Mark II Programmer's Guide
Preface
THIS PAGE INTENTIONALLY LEFT BLANK
ii
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Table of Contents
Table of Contents
Preface................................................................................................................................................. i
Chapter 1 Introduction..................................................................................................................... 1
Overview ......................................................................................................................................... 1
Common Terms and Phraseology.................................................................................................... 1
Encryption Notation ........................................................................................................................ 1
Supplemental Documentation.......................................................................................................... 2
Host Function Overview.................................................................................................................. 2
Chapter 2 Function Construction.................................................................................................... 5
Host Function Overview.................................................................................................................. 5
Function Message Formats.............................................................................................................. 5
Variable Length Fields in Function Request and Response Messages ........................................... 6
Variants............................................................................................................................................ 9
Public Key Verification Code........................................................................................................ 10
The ‘Key Specifier’ Function Field............................................................................................... 11
Function Identifier Control............................................................................................................ 20
Message Meta-function Format..................................................................................................... 20
Chapter 3 The Metafunction.......................................................................................................... 21
Message Meta-function Format..................................................................................................... 21
Chapter 4 HSM Status Functions.................................................................................................. 25
The Error Log ................................................................................................................................ 25
Chapter 5 KM Change Functions ................................................................................................. 33
Chapter 6 Transfer Functions ....................................................................................................... 39
Chapter 7 HSM Software Upgrade Functions ............................................................................. 47
Chapter 8 EFT Terminal Functions.............................................................................................. 53
Initial Session Key Generation ...................................................................................................... 58
Rollover Session Key Generation.................................................................................................. 61
Docutel Key Generation ................................................................................................................ 63
3624 Comms Key Generation ....................................................................................................... 64
Terminal Verification .................................................................................................................... 65
DUKPT BDK Generation.............................................................................................................. 66
Chapter 9 Remote ATM Initialization Functions ........................................................................ 67
Overview ....................................................................................................................................... 68
Key Types...................................................................................................................................... 68
Authentication of public keys........................................................................................................ 68
Storage of RSA keys...................................................................................................................... 69
Chapter 10 Interchange Functions................................................................................................ 83
Initial Session Key Generation ...................................................................................................... 84
Receive Initial Session Key........................................................................................................... 88
Rollover Session Key Generation.................................................................................................. 91
Receive Rollover Session Key ...................................................................................................... 93
Chapter 11 PIN Management Functions ...................................................................................... 95
Host Stored PVK Management ..................................................................................................... 95
PIN Encryption .............................................................................................................................. 97
PIN Translation............................................................................................................................ 100
PINKEY PIN Translation............................................................................................................ 104
© SafeNet, Inc.
iii
ProtectHost White Mark II Programmer's Guide
Table of Contents
Base Key PIN Verification ..........................................................................................................105
Base Key PIN Verification - Variable Length .............................................................................106
PIN Offset Generation .................................................................................................................107
Chapter 12 Online Banking Module Functions..........................................................................119
Licensing Requirements...............................................................................................................119
Online Banking Module Password Restrictions ..........................................................................119
Function Field Constructs ............................................................................................................120
Chapter 13 Visa Functions ...........................................................................................................141
Visa Overview..............................................................................................................................141
Key Management Operations.......................................................................................................143
Visa Function Overview ..............................................................................................................145
Visa 3DES Support ......................................................................................................................146
Diebold Table Support .................................................................................................................152
SEED Translation ........................................................................................................................156
Chapter 14 MAC Management Functions..................................................................................161
MAC Generation..........................................................................................................................162
Terminal Master Key MAC Generation ......................................................................................168
Chapter 15 Data Ciphering Functions ........................................................................................169
3624 B-Key Enciphering .............................................................................................................180
3624 B-Key Deciphering .............................................................................................................181
Chapter 16 MasterCard Functions..............................................................................................183
MasterCard Security Requirements .............................................................................................183
Facilities for MasterCard Support................................................................................................183
MasterCard 3DES Support...........................................................................................................184
Chapter 17 American Express Functions ...................................................................................191
Card Security Code Keys (CSCK)...............................................................................................191
Chapter 18 PIN Issuance Functions ............................................................................................197
PIN Issuance Overview................................................................................................................198
Separating PIN Generation and Printing......................................................................................198
Chapter 19 EMV Functions..........................................................................................................205
Chapter 20 CEPS Functions.........................................................................................................247
Chapter 21 AS2805.6.3 Support Functions.................................................................................255
Chapter 22 Key Block ...................................................................................................................261
Chapter 23 ZKA Functions ..........................................................................................................265
Session Key Derivation................................................................................................................265
Pin Verification ............................................................................................................................266
Chapter 24 Administration Functions.........................................................................................283
Chapter 25 ABI Debit Card Functions........................................................................................287
Chapter 26 Superceded Functions...............................................................................................291
Appendix A IBM 3624 PIN Verification Method.......................................................................341
Definitions....................................................................................................................................341
Verification of a Derived PIN ......................................................................................................342
Verification of a Random PIN .....................................................................................................343
Selecting Significant Offset Digits ..............................................................................................344
Appendix B EFT Terminal Functions .........................................................................................345
Appendix C PIN Management Function Examples ...................................................................347
iv
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Table of Contents
Appendix D EMV Function Examples........................................................................................ 349
Appendix E American Express Account Blocks ........................................................................ 355
How To Form An Account Block ............................................................................................... 355
34 Cards....................................................................................................................................... 355
Appendix F American Express Examples .................................................................................. 357
Test Program Output ................................................................................................................... 357
Appendix G Function Matrix ...................................................................................................... 361
Appendix H PTK EFT MK2........................................................................................................ 367
Structures Representing Individual Key Specifiers..................................................................... 367
Structure Representing All Key Specifiers.................................................................................. 370
Structure Representing Variable Length Character Arrays......................................................... 371
API Helper Functions .................................................................................................................. 371
Error Translation Functions......................................................................................................... 372
Optional IO Fields in Functions .................................................................................................. 372
PTK EFT MK2 Functions ........................................................................................................... 372
Appendix I Error Codes............................................................................................................... 395
Appendix J References ................................................................................................................. 397
Appendix K Glossary.................................................................................................................... 399
Appendix L Function List ............................................................................................................ 403
© SafeNet, Inc.
v
ProtectHost White Mark II Programmer's Guide
Table of Contents
THIS PAGE INTENTIONALLY LEFT BLANK
vi
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 1
Introduction
Chapter 1
Introduction
Overview
This Guide covers standard Mark II functionality. It provides a complete function reference for all
functions that make up the Mark II function set. This function set, which is 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 functions are available as standard on three SafeNet HSM products. These are the;
• ProtectHost White Mark II,
• ProtectHost White Card Issuance and
• ProtectServer Orange
The Mark II function set is not implemented in its entirety on each of these HSM products. Rather, a
unique subset of Mark II functions is provided to suit HSM design and application requirements in
each case.
Additionally, further functions may also be available.
• Functions from the Card Issuance function set are available in addition to Mark II functions on
ProtectHost White Card Issuance HSMs. Details can be found in the ProtectHost White Card
Issuance Programmers Guide.
• 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 ProtectToolkit EFT product provides an application programming interface in the ‘C’
programming language. The PTK EFT MK2, is a component within this product, that allow third
parties to easily interface to the ProtectHost White and ProtectServer Orange security modules
running the MarkII software. The PTK EFT MK2 is also described in this Guide.
Common Terms and Phraseology
Other documentation may refer to an SafeNet security module as an ESM or ESM2000. This device
has been renamed ProtectHost White. The names ProtectHost White, ESM, HSM and ESM2000 all
refer to the same device in the context of this or previous Guides.
There is a glossary at the back of this Guide that 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.
1
ProtectHost White Mark II Programmer's Guide
Chapter 1
Introduction
Supplemental Documentation
The ProtectHost White Programmers Guide is supplemental to the following documentation:
•
•
•
•
ProtectHost White Installation & Maintenance Guide
ProtectHost White Communications Guide
ProtectHost White Mark II Console User Guide
ProtectToolkit EFT Installation Guide
For ProtectHost White Card Issuance users:
•
•
ProtectHost White Card Issuance Programmers Guide
ProtectHost White Card Issuance Console Guide
Additionally, further customer 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 ProtectHost White. 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 ProtectHost White 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 entitiled Appendix G Function Matrix.
To the right of the function name, a table lists the products in which the function is supported. PHW
refers to the ProtectHost White product running the Mark II software. PSO refers to the ProtectServer
Orange product running the Mark II software. PTK EFT MK2 refers to the ProtectTookit EFT MK2
2
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 1
Introduction
application programming interface (API). Card Issuance refers to the ProtectHost White 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 PTK
EFT MK2, the function definition is provided following the specification, as illustrated below.
Figure 1 Function definition format
© SafeNet, Inc.
3
ProtectHost White Mark II Programmer's Guide
Chapter 1
Introduction
THIS PAGE INTENTIONALLY LEFT BLANK
4
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 2
Function Construction
Chapter 2
Function Construction
Host Function Overview
Each function involves a host request being sent to the ProtectHost White. 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 ProtectHost White 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
Function Message Formats
Data Item Representation in Request/Response Messages
Request and response content may use the following operators and qualifying letters.
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
Each field has an associated attribute and its length in bytes. The attributes are defined as follows:
© SafeNet, Inc.
5
ProtectHost White Mark II Programmer's Guide
Chapter 2
Function Construction
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
Length
Attribute
Function Code
1
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
Length
Attribute
Function Code
1
h
Return Code
1
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.
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 utilise 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:
6
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Length of length prefix
(bytes)
1
2
3
4
…
Chapter 2
Function Construction
Length indicator bits in most significant byte
0…
10…
110 …
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:
Length of
length prefix
(bytes)
1
2
3
4
…
Values in length prefix
(hex)
00 – 7F
8000 – BFFF
C00000 – DFFFFF
E0000000 – EFFFFFFF
Bytes in data value
(hex)
00 – 7F
0000 – 3FFF
000000 – 1FFFFF
00000000 – 0FFFFFFF
(dec)
0 – 127
0 – 16383
0 – 2097151
0 – 268435455
The following points apply to the Mark II implementation of the method.
•
A variable-length data value and its associated length prefix form a single field in a function
request or request message, with an indicated length of ‘Var’. Therefore, there is no need to
indicate the length as a separate field.
•
The length prefix indicates the length of the data portion of the field, i.e. the length prefix is not
included in the length. The specified length is a number of bytes.
•
The length prefix is independent of the attributes and contents of the data value.
•
For multi-byte length prefixes, the byte order in the field is most significant byte first, i.e. big
endian. This is in line with the general rule for all multi-byte integer fields in Mark II functions.
•
The method as defined above is open-ended, and therefore could be extended to a length prefix
of more than four bytes. However, the ProtectHost White 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.
© SafeNet, Inc.
7
ProtectHost White Mark II Programmer's 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
b13 b12 b11 b10 b09 b08
msb
1sb
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
b20 b19 b18 b17 b16
msb
1sb
b15 b14 b13 b12 b11 b10 b09 b08
msb
1sb
b07 b06 b05 b04 b03 b02 b01 b00
1
0
indicates three byte length field
1
Length is 21 bit binary number (b20b19...b01b00)
Four byte length
First byte transmitted
Second byte transmitted
Third byte transmitted
Fourth byte transmitted
msb
1
1
1
0
1sb
b27 b26 b25 b24
msb
1sb
b23 b22 b21 b20 b19 b18 b17 b16
msb
1sb
b15 b14 b13 b12 b11 b10 b09 b08
msb
1sb
b07 b06 b05 b04 b03 b02 b01 b00
1
1
0
indicates four byte length field - Length is 28 bit binary number (b27b26...b01b00)
8
1
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
16
17
18
19
20
24
25
26
27
30
31
32
33
34
35
36
37
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’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’
Used to encrypt:
DPK
PPK
MPK
KIS
KIR
KTM
CSCK
KPV, DT
KPVV
KCVV
Key Block encryption - terminal
Key Block message authentication –terminal
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
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.
© SafeNet, Inc.
Variant Byte
X'24'
Used to Protect
MPK
X'28'
PPK
9
ProtectHost White Mark II Programmer's Guide
Chapter 2
Function Construction
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
3
Variant Byte
X'08'
Used to Protect
PPK
X'10'
DPK
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 '
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 concaternating 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 conatant is obtained by concaternating the variant
byte from the above table with the constant x30 and repeating
these 2 bytes 12 times to yield a 24 byte constant.
Public Key Verification Code
The KVC for a public key (PVC) is formed as described in AS2805 part 6.1 as follows:
•
•
10
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
•
Chapter 2
Function Construction
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 utilise 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.
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
© SafeNet, Inc.
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
11
ProtectHost White Mark II Programmer's Guide
Index - long / BCD
Format 02
Field length: 3
Chapter 2
Function Construction
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
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 - 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
12
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 2
Function Construction
Host-stored key / authenticated / with attributes
Field Content
Length
Attribute Description
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.
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.
(See KIS/KIR Attributes below)
Attributes
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.
13
ProtectHost White Mark II Programmer's 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 hex-ASCII).
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
Format 19
Data Specifier
Type
Encrypted Payload
KM-Id
14
Length
1
1
Attribute
h
h
1
1
h
h
Description
19
= 02 – CAP Bitmap
= 00 - payload is not encrypted
For the AMB HSM, identifies the KM
used, otherwise must be zero.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Host-stored bitmap
Field Content
Payload Length
Pad1
Bitmap
Authentication
Code
Length
2
2
8
8
Chapter 2
Function Construction
Attribute
h
h
h
h
Description
= 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
2= double length (TDEA transaction key
is derived)
This key specifier calculates a unique-per-card derived key. It is used to derive KKEK (as defined in
[32]) 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
Format 50
1
KMC
Var
Card-unique
derivation data
Card method
Attribute
h
K-Spec
16
h
1
h
Description
50
Key specifier for personalisation 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]) in support of the mutual authentication of the card being
personalised and its host. CardMethod (01 or 02) and SessionMethod (01 or 02) define the mode of
encryption.
Unique-per-card derived session key
Field Content
Length
Attribute Description
Format 51
1
h
51
KMC
Var
K-Spec
Key specifier for personalisation master
key
(format 0 –3, 13).
Card-unique
16
h
derivation data
Card method
1
h
= 01: ECB
= 02: CBC
Session data
16
h
Session method
1
h
= 01: ECB
= 02: CBC
© SafeNet, Inc.
15
ProtectHost White Mark II Programmer's Guide
Chapter 2
Function Construction
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.
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
16
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 2
Function Construction
The following Key Specifier Format specifies the format for a ZKA Random Number. This key
specifier incorporates the data required to produce a clear PAC or MAC session key. A PAC key is
produced if the key specifier is used within a PIN management function and a MAC key is produced
if the key specifier is used within a message authentication function. It can also incorporate a format
92 key specifier as the MK-spec, in order to access a key in the MK2 table.
This key specifier format can also be used as an alternative format in a PPK-spec or MPK-spec
request field in standard functions. Specifically, the following functions will support a ZKA-RND
format key specifier:
• MAC-UPDATE, MAC-GEN-FINAL, MAC-VER-FINAL
• PIN-TRANSLATE
• PIN-VERIFY, Calculate IBM Offset, MIGRATE-PIN
• PIN Verify – PVV, Calculate PVV from IBM Offset, Calculate PVV from PIN
Encrypted session key
Attribute
Description
h
= 90
Field Content
Format
Length
1
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 (ProtectHost White Mark II).
The following Control Vector values are used when constructing a format 90 host stored key
specifier. Key values for each type are defined below.
Type
MAC
CV1
00 00 4D 00 03 41 00 00
CV2
00 00 4D 00 03 21 00 00
PAC
00 21 5F 00 03 41 00 00
00 21 5F 00 03 21 00 00
The following Key Specifier Format specifies the format for a ZKA-Derived-*KK. This key
specifier incorporates the data required to derive a *KKBLZ as follows:
*KKBLZ = e*KGK1 (BLZ | BLZ) | e*KGK2 (BLZ | BLZ)
The key specifier may be used in the functions that contain a '*KK-spec' field, i.e. 'ZKA-PIN-VER –
ecPVN method ' and 'ZKA-Calculate PVN – from encrypted PIN'
© SafeNet, Inc.
Length
ZKA-Derived-*KK
Attribute
h
= 91
Field Content
Format
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
17
ProtectHost White Mark II Programmer's Guide
Chapter 2
Function Construction
The following Key Specifier Format specifes 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) specifes 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 ciphertext Block has a length of 8 bytes.
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
18
Length
KM-encrypted PIN
Attribute
Description
Format
1
h
= 1A
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 2
Function Construction
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 HSMstored 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.
-
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-SHA-1
MPK keys are only applied for use with HMAC-SHA-1 algorithm.
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.
© SafeNet, Inc.
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
19
ProtectHost White Mark II Programmer's Guide
Chapter 2
Function Construction
A particular function may not support all of the formats identified above. The specification of each
function identifies which formats it supports.
Function Identifier Control
The Function Identifier Control allows the ProtectHost White 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.
20
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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: that 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 ProtectHost White 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
Meta-function
Indicator
Meta-function
Type
Version
Type specific
data …
Comms trailer
Type specific
data …
Comms trailer
Type specific
data …
Comms trailer
Response Message
Comms
Header
Meta-function
Indicator
Meta-function
Type
Version
Response
Code
(= 00)
Meta-function Error Response Message
Comms
Header
Meta-function
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 variablelength 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 ProtectHost White 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.
21
ProtectHost White Mark II Programmer's Guide
Chapter 3
The Metafunction
Metafunction
PHW
PSO
PTK EFT MK2
Card Issuance
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
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
Data
22
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
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 3
The Metafunction
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.
23
ProtectHost White Mark II Programmer's Guide
Chapter 3
The Metafunction
THIS PAGE INTENTIONALLY LEFT BLANK
24
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 4
HSM Status Functions
Chapter 4
HSM Status Functions
Summary of HSM Status Functions
Function Name
Function Code
Page
HSM_STATUS
01
26
HSM-ERRORLOG-STATUS
FFF0
28
HSM-GET-ERRORLOG
FFF1
30
The Error Log
The error log consists of one or more text files stored on the hard disk of the ProtectHost White. If an
error condition is generated by the ProtectHost White software that error condition is written to the
ProtectHost White 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 ProtectHost White 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 ProtectHost White 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.
25
ProtectHost White Mark II Programmer's Guide
Chapter 4
HSM Status Functions
HSM_STATUS
PHW
PSO
PTK EFT MK2
Card Issuance
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
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
Calls in last
minute
Calls in last 10
mins
Software ID
length
26
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 and 1 = failed.
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
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Software ID
ESMID
Chapter 4
HSM Status Functions
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 PTK EFT 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 PTK EFT product suite.
PTK EFT 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);
27
ProtectHost White Mark II Programmer's Guide
Chapter 4
HSM Status Functions
HSM-ERRORLOG-STATUS
PHW
PSO
PTK EFT MK2
Card Issuance
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 Errorlog Files
1
h
00 if no errorlog file created
Repeat for each errorlog file:
Errorlog File Number
Total No of Errors logged
First Errorlog Date
First Errorlog Time
Last Errorlog Date
Last Errorlog Time
1
2
8
6
8
6
h
h
h
h
h
h
00 to 10 max.
0 to 65,535 max, big-endian
ASCII ddmmyyyy format
ASCII hhmmss format
ASCII ddmmyyyy format
ASCII hhmmss format
D
U
D
D
This function checks for system errorlog files and returns the results to the host. The system will log
errors to a current errorlog 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 archived file is overwritten.
The current errorlog file is file number 0, and the archives range from 1 to 10. If no system errors
have occurred then the errorlog file may not have been created. This will return a value of zero in the
“No of Errorlog Files” field, otherwise this field will be the total of the current errorlog file plus each
archived file.
The function returns the number of errors logged in each errorlog 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
errorlog file. The details of the errorlog can be obtained by using the HSM_GET_ERRORLOG
function specifying the appropriate errorlog 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
28
Part of the PTK EFT 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 PTK EFT product suite.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 4
HSM Status Functions
PTK EFT 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] );
29
ProtectHost White Mark II Programmer's Guide
Chapter 4
HSM Status Functions
HSM-GET-ERRORLOG
PHW
PSO
PTK EFT MK2
Card Issuance
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
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
30
Part of the PTK EFT 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 PTK EFT product suite.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 4
HSM Status Functions
PTK EFT 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);
31
ProtectHost White Mark II Programmer's Guide
Chapter 4
HSM Status Functions
THIS PAGE INTENTIONALLY LEFT BLANK
32
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
34
KM_Migrate
12
35
Erase_Old_KM
13
37
33
ProtectHost White Mark II Programmer's Guide
Chapter 5
KM Change Functions
Establish_KM
PHW
PSO
PTK EFT MK2
Card Issuance
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
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.
PTK EFT MK2
int EFT_11_EstablishKM(void);
34
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 5
KM Change Functions
KM_Migrate
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
12
Length
1
Attribute
h
Description
Function Code
1
1
Var
h
h
K-Spec
Length
1
1
Attribute
h
h
KM Variant Used
Number of Keys
A key specifier for type of host-stored
key used (Formats: 10, 11, 18, 81, 82)
Description
Function Code
Return Code
1
Var
h
K-Spec
i
n
1
Key Spec
Response Content
12
rc
n
Key Spec
1
1
D
D
D
D
Number of Keys
A key specifier for key encrypted
under Current KM
(Formats: 10, 11, 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.
Definitions
Key Spec
Single or double length key specifier
i
Variant of the Domain Master Key.
© SafeNet, Inc.
35
ProtectHost White Mark II Programmer's Guide
Chapter 5
KM Change Functions
PTK EFT MK2
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
36
UCHAR
KEYSPEC
KEYSPEC
KEYSPEC
KEYSPEC
KEYSPEC
KEYSPEC
KEYSPEC
KEYSPEC
KEYSPEC
KEYSPEC
variantNum,
NumKeys,
*keyToTranslate1,
*keyToTranslate2,
*keyToTranslate3,
*keyToTranslate4,
*keyToTranslate5,
*keyToTranslate6,
*keyToTranslate7,
*keyToTranslate8,
*keyToTranslate9,
*keyToTranslate10,
*NumKeysReturned,
*translatedKey1,
*translatedKey2,
*translatedKey3,
*translatedKey4,
*translatedKey5,
*translatedKey6,
*translatedKey7,
*translatedKey8,
*translatedKey9,
*translatedKey10);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 5
KM Change Functions
Erase_Old_KM
PHW
PSO
PTK EFT MK2
Card Issuance
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
Used to erase the old KM. This function is enabled/disabled by a console operation.
PTK EFT MK2
int EFT_13_EraseOldKM(void);
© SafeNet, Inc.
37
ProtectHost White Mark II Programmer's Guide
Chapter 5
KM Change Functions
THIS PAGE LEFT INTENTIONALLY BLANK
38
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 6
Transfer Functions
Chapter 6
Transfer Functions
Summary of Transfer Functions
© SafeNet, Inc.
Function Name
Function Code
Page
Retrieve_Key
21
40
Store_Key
22
41
KEY_IMPORT
EE0200
42
KEY_EXPORT
EE0201
44
Get_Key_Details
EE0202
46
39
ProtectHost White Mark II Programmer's Guide
Chapter 6
Transfer Functions
PHW
D
PSO
D
PTK EFT MK2
D
Card Issuance
D
Retrieve_Key
Request Content
21
FM
Length
1
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
Length
1
1
Attribute
h
h
Key specifier for Key Transfer Table
(Formats: 0 - 3)
Description
Function Code
Return Code
Key Type
1
h
Key Spec
Var
K-Spec
3
h
KXT Spec
Response Content
21
rc
KVC
Representing returned Key Type:
01 = KIS
02 = KIR
03 = ZCMK
Key specifier for retrieved key
(Formats: 10, 11, 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 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.
PTK EFT MK2
int EFT_21_RetrieveKey(
IN UCHAR
Reserved[2],
IN KEYSPEC
*tfrTableIndex,
OUT UCHAR
OUT KEYSPEC
OUT UCHAR
40
*keyType,
*retrievedKey,
KVC[3] );
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 6
Transfer Functions
PHW
D
PSO
D
PTK EFT MK2
D
Card Issuance
D
Store_Key
Request Content
22
FM
Length
1
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
KXT Spec
Var
K-Spec
Key Type
1
h
Key Spec
Var
K-Spec
3
Length
1
1
h
Attribute
h
h
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
KVC
Response Content
22
rc
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.
PTK EFT MK2
int EFT_22_StoreKey(
IN UCHAR
IN KEYSPEC
IN UCHAR
IN KEYSPEC
IN UCHAR
© SafeNet, Inc.
Reserved[2],
*tfrTableIndex,
keyType,
*keyToStore,
KVC[3]);
41
ProtectHost White Mark II Programmer's Guide
Chapter 6
Transfer Functions
PHW
D
PSO
D
PTK EFT MK2
D
Card Issuance
D
KEY_IMPORT
Request Content
EE0200
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
KIR Spec
Var
K-Spec
Key Type
Enc Mode
1
1
d
h
eKIRvx(K)
Var
h
Length
3
1
Attribute
h
h
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
Var
K-Spec
3
h
Response Content
EE0200
rc
Key Spec
KVC
Key specifier containing eKMx(K)
(Formats: 10, 13)
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 singlelength 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.
FM
= 00. Must be set to zero.
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:
00: DPK
01: PPK
02: MPK
03: KIS
04: KIR
05: KTM
Enc Mode
42
18:ZKA MK
24: BDK
30: IMKAC
31: IMKSMI
32:IMKSMC
33: IMKDAC
34: IMKDN
35: KTK
36: PTK
37: KMC
Indicates the mode of operation used for decrypting the incoming key:
0
1
eKIRVx(K)
06: CSCK
07: KPV, DT
08: KPVV
09: KCVV
16: ZKA KGK
17: ZKA KKBLZ
ECB
CBC
Key encrypted by a variant of the Interchange Receive Key. Accepts key spec
formats 10, 11 and 13.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 6
Transfer Functions
Key Spec
Key Specifier incorporating an encrypted key. Single length ECB and double
length CBC encrypted keys (Formats 10, 13).
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 the ProtectHost White 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
PTK EFT MK2
int EFT_EE0200_KeyImport(
IN
UCHAR
FM,
IN
KEYSPEC
*KIR,
IN
UCHAR
KeyType,
IN
UCHAR
EncMode,
IN
EFTBUFFER
*eKIRvK,
OUT
OUT
© SafeNet, Inc.
KEYSPEC
UCHAR
*eKMvK,
KVC[3]);
43
ProtectHost White Mark II Programmer's Guide
Chapter 6
Transfer Functions
PHW
D
PSO
D
PTK EFT MK2
D
Card Issuance
D
KEY_EXPORT
Request Content
EE0201
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
KIS Spec
Var
K-Spec
Key Type
Enc Mode
1
1
d
h
Key Spec
Var
K-Spec
Length
3
1
Attribute
h
h
Key specifier for the KIS, Formats
(Formats: 0 - 3, 10, 11, 13, 15)
Key type
Encryption Mode (for encipher of
outbound eKISvx(K).)
Key specifier containing eKMx(K)
(Formats: 10, 13, 14)
Description
Function Code
Return Code
Var
3
h
h
Response Content
EE0201
rc
eKISvx(K)
KVC
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
44
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
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 and 13).
KVC
Key Verification Code for the key
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 6
Transfer Functions
Details and Restrictions
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 ProtectHost White 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
PTK EFT 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]);
45
ProtectHost White Mark II Programmer's Guide
Chapter 6
Transfer Functions
PHW
D
PSO
D
PTK EFT MK2
D
Card Issuance
D
Get_Key_Details
Request Content
EE0202
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Key Spec
Var
K-Spec
Key Type
1
h
1
Length
3
1
h
Attribute
h
h
Key specifier for the host stored key
(Formats: 10,11,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
Parity
1
h
KVC
Var
h
KVC Type
Response Content
EE0202
rc
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
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 whther 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
PTK EFT MK2
int EFT_EE0202_GetKeyDetails(
IN
UCHAR
FM,
IN
KEYSPEC
*K,
IN
UCHAR
KeyType,
IN
UCHAR
KVCType,
OUT
OUT
46
UCHAR
EFTBUFFER
*Parity,
*KVC);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
48
HSM_SOFTWARE_STATUS
EE3101
50
47
ProtectHost White Mark II Programmer's Guide
Chapter 7
HSM Software Upgrade Functions
LOAD_HSM_SOFTWARE
PHW
PSO
PTK EFT MK2
Card Issuance
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
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
48
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 PTK EFT MK2 function call. The ESMID is a pointer to a NULL
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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 PTK EFT product suite.
PTK EFT 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]);
49
ProtectHost White Mark II Programmer's Guide
Chapter 7
HSM Software Upgrade Functions
HSM_SOFTWARE_STATUS
PHW
PSO
PTK EFT MK2
Card Issuance
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
Representing Loaded Software’s
version number.
Version
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
This field represents stauts of Loaded Software on a HSM box.
00
50
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.
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 PTK EFT MK2 function call. The ESMID is a pointer to a NULL
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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 PTK EFT product suite.
PTK EFT MK2
int EFT_EE3101_ HSMSoftwareStatus(
IN
UCHAR
*ESMID,
IN
UCHAR
FM,
OUT
OUT
© SafeNet, Inc.
UCHAR
EFTBUFFER
*Status,
*Version);
51
ProtectHost White Mark II Programmer's 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
54
EE0400
58
Initial Session Key Generation
IT_KEY_GEN
Rollover Session Key Generation
NT_KEY_GEN
EE0401
61
47
63
49
64
EE0406
65
EE0408
66
Docutel Key Generation
D51-PPK-GEN
3624 Comms Key Generation
M-DPK-GEN
Terminal Verification
TERM_VER_2
DUKPT BDK Generation
BDKGEN
© SafeNet, Inc.
53
ProtectHost White Mark II Programmer's Guide
Chapter 8
EFT Terminal Functions
Key Mailer
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0E01
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00 or 01
nA
Line No.
Column No.
Data
nB
Line No.
Column No.
Data
Response Content
EE0E01
rc
1
1
1
Var
1
1
1
Var
Length
3
1
h
h
h
h
h
h
h
h
Attribute
h
h
Number of text fields for env. ‘A’
Var
Key-Spec
eKMvX(key)
D
U
D
D
Number of text fields for env. ‘B’
Description
Function Code
Return Code
Encrypted key (Formats: 10, 13)
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.
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 = 00, 01. Note: If FM = 01, request content, nB,
moves to a position under nA in chart above.
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 ASCII data to be
printed.
nB
Number of text fields to print on the ‘B’ envelope (max.10).
eKMvX(key)
“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.
Single length generated keys are Format 10, double length are
Format 13
54
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
ESMID
Chapter 8
EFT Terminal Functions
Part of the PTK EFT 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
PTK EFT product suite.
Note that each optional item to be printed is defined by appending a set of the fields ‘Line no.’,
‘Column no.’, and ‘Data’ to the host request. Each ‘Data’ character must be printed within the area
defined by the size of the key mailer envelope. Also, each ‘Data’ character must not overprint any
other defined area (including other defined ‘Data’ areas).
Return code
02
Error condition
Illegal Function Code (that is, the Key Mailer facility was not enabled when the
Key Mailer request was received).
04
Invalid data in message:
This condition occurs if:
- One of the fields ‘Line No.’ or ‘Column No.’ contains an invalid value.
- A non-printable ASCII character (not in the range 20H to 7EH) is found in a
‘Data’ field.
- 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.
0B
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.
PTK EFT MK2
PTK EFT MK2 only supports the function when used with = 00 FM=01.
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
UCHAR *LineNo5a,
55
ProtectHost White Mark II Programmer's Guide
56
_IN
_IN
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,
_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
UCHAR *LineNo10b,
Chapter 8
EFT Terminal Functions
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
© SafeNet, Inc.
_IN
_IN
UCHAR *ColumnNo10b,
EFTBUFFER
*Data10b,
OUT
KEYSPEC
Chapter 8
EFT Terminal Functions
*eKMvX_KEY);
57
ProtectHost White Mark II Programmer's Guide
Chapter 8
EFT Terminal Functions
Initial Session Key Generation
IT_KEY_GEN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0400
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
2
Length
3
1
h
Attribute
h
h
A key specifier for the KTM
(Formats: 0 - 3, 10, 11, 13, 16)
Key Type generation specifier
Description
Function Code
Return Code
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
U
Number of following key sets
Encrypted Session Key
Key specifier incorporating
encrypted Session Key
(Formats: 10, 11, 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.
58
FM
= 00. Must be set to zero.
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Key Flags
Chapter 8
EFT Terminal Functions
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
Return code
0C
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).
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.
•
•
© SafeNet, Inc.
This function supercedes functions 41,42,43, 4A
Bit 7 and Bits 13-15 of the key flags are reserved.
59
ProtectHost White Mark II Programmer's Guide
Chapter 8
EFT Terminal Functions
PTK EFT MK2
int EFT_EE0400_InitialSessionKeyGeneration(
IN
UCHAR
FM,
IN
KEYSPEC
*KTM,
IN
UCHAR
KeyFlags[2],
60
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] );
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 8
EFT Terminal Functions
Rollover Session Key Generation
NT_KEY_GEN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0401
FM
Key Flags
1
KSn Spec
Response Content
EE0401
rc
n
eKSn(KSn+1)
1
KSn+1 Spec
1
1
1
KVC
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
2
Var
h
K-Spec
Length
3
1
Attribute
h
h
Key Type generation specifier
Session Key Specifier
(Formats: 10, 11)
Description
Function Code
Return Code
1
Var
Var
h
h
K-Spec
3
h
D
D
D
U
Number of following key sets
Encrypted Session Key
Session Key specifier
(Formats: 10, 11)
Key Verification Code
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.
FM
= 00. Must be set to zero.
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).
Reserved. Must be zero.
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 response eKSn(KSn+1):
encryption. 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’;
•
© SafeNet, Inc.
To generate a single-length PIN encrypting key and a double-length
61
ProtectHost White Mark II Programmer's Guide
Chapter 8
EFT Terminal Functions
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.
PTK EFT MK2
int EFT_EE0401_RolloverSessionKeyGeneration(
IN
UCHAR
FM,
IN
UCHA R
KeyFlags[2],
IN
KEYSPEC
*KSi1,
_IN
KEYSPEC
*KSi2,
_IN
KEYSPEC
*KSi3,
62
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]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 8
EFT Terminal Functions
Docutel Key Generation
D51-PPK-GEN
PHW
PSO
PTK EFT MK2
Card Issuance
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
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.
63
ProtectHost White Mark II Programmer's Guide
Chapter 8
EFT Terminal Functions
3624 Comms Key Generation
M-DPK-GEN
PHW
PSO
PTK EFT MK2
Card Issuance
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
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 ProtectHost White. It is also returned
encrypted under KM, for storage within the host.
64
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 8
EFT Terminal Functions
Terminal Verification
TERM_VER_2
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0406
FM
KTM-Spec
SEC-No
Logon-Data
Response Content
EE0406
rc
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifer = 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
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.
PTK EFT MK2
int EFT_EE0406_TerminalVerification (
IN
UCHAR
FM,
IN
KEYSPEC
*KTM,
IN
UCHAR
SecurityNumber[8],
IN
UCHAR
LogonData[8] );
© SafeNet, Inc.
65
ProtectHost White Mark II Programmer's Guide
Chapter 8
EFT Terminal Functions
DUKPT BDK Generation
BDKGEN
PHW
PSO
PTK EFT MK2
Card Issuance
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
U
D
U
Description
Function Code
Function Modifer = 00
Length of BDK
02 = Double Length
03 = Triple Length
Description
Function Code
Return Code
Key specifier incorporating
encrypted BDK key
(Formats: 13, 14)
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.
PTK EFT MK2
int EFT_EE0408_DUKPT_BDK_Generation(
IN
UCHAR
FM,
IN
UCHAR
KeyLength,
OUT
66
KEYSPEC
*BDK);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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.........................................
EE9001 ............................... 70
EE9003 ............................... 72
EE9004 ............................... 73
EE9005 ............................... 75
EE9006 ............................... 76
EE9007 ............................... 77
EE9008 ............................... 78
EE9101 ............................... 79
EE9102 ............................... 80
EE9201 ............................... 81
© SafeNet, Inc.
Page
67
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
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:
•
•
•
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 ProtectHost White will support 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 ProtectHost White 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 ProtectHost White. 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.
68
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Storage of RSA keys
Mark II functionality incorporates a table of 16 ProtectHost White stored (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 ProtectHost White.
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 specifiers that support host-stored keys are defined in Chapter 2 Function Construction.
© SafeNet, Inc.
69
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Generate RSA Key Pair
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE9001
FM
Key Type
Length
3
1
Attribute
h
h
2
h
Description
Function Code
Function Modifer = 00
Indicates the valid usage for the private
key
bit
0
1
2
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
D
D
D
U
key type
--- not valid --Data Signature
Key Transport
Bit 0 is the least significant (rightmost)
bit.
Modulus size in bytes:
= 3 or 65537 (216+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.
4.
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.
70
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Diebold
NCR
Chapter 9
Remote ATM Initialization Functions
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
PTK EFT 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);
71
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Import Public Key
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE9003
FM
Key Type
Length
3
1
Attribute
h
h
2
h
Description
Function Code
Function Modifer = 00
Indicates the valid usage for the private
key
bit
0
1
2
PK
Var
K-Spec
User Data
Var
h
Length
3
1
Attribute
h
h
Var
K-Spec
Response Content
EE9003
rc
PK
D
D
D
U
key type
Certificate
Data Signature
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.
PTK EFT MK2
int EFT_EE9003_ImportPublicKey (
IN
UCHAR
FM,
IN
UCHAR
KeyType[2],
IN
KEYSPEC
*PKi,
IN
EFTBUFFER
*UserData,
OUT
72
KEYSPEC
*PKo);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Import public key certificate
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE9004
FM
D
D
D
U
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifer = 00
Var
K-Spec
Certificate Format
1
h
Hash Function
1
h
Var
2
h
h
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
PKCA
Certificate
Key Type
bit
0
1
2
User Data
Response Content
EE9004
rc
PK
Var
h
Length
3
1
Attribute
h
h
Var
K-Spec
key type
Certificate
Data Signature
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
[21].
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.
73
ProtectHost White Mark II Programmer's 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 [21].
Certificate
Format
If equal to 03 (NCR), the data in the Certificate field takes the format: modulus
(256 bytes) concatenated with signature (256 bytes).
If equal to 04 (NCR2), the data in the Certificate field is represented in
PKCS#1, ASN.1 type RSAPublicKey.
RSAPublicKey ::= SEQUENCE {
modulus INTEGER, -- n
publicExponent INTEGER, -- e
}
The fields of type RSAPublicKey have the following meanings:
• modulus is the modulus n.
• publicExponent is the public exponent e.
The following table illustrates a certificate in the PKCS#1, ASN.1 type RSAPublicKey (i.e. Certificate
format = 04 - NCR2 ).
Component
Sequence and length
ASN.1 Integer type and length
ASN.1 Modulus (257 bytes – 256 byte modulus
preceeded 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
preceeded by the variable length prefix described in Chapter 2 Function Construction.
PTK EFT 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
74
KEYSPEC
*PK);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Sign Data
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE9005
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifer = 00
Var
K-Spec
1
1
h
h
Var
Length
3
1
h
Attribute
h
h
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
Var
h
Signed data: sSK(Data) or sSK(h(Data))
SK
Signature Algorithm
Hash Function
Data
Response Content
EE9005
rc
D
D
D
U
Signature
This function signs the data using the private key and signature algorithm indicated, and returns the
digital signature.
Function usage (in context of Remote ATM Initialization)
None.
PTK EFT 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);
75
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Verify Signed Data
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE9006
FM
PK
Signature Algorithm
Hash Function
Data
sSK(Data) or
sSK(h(Data))
Response Content
EE9006
rc
D
D
D
U
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifer = 00
Var
K-Spec
1
1
h
h
Var
Var
h
h
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
Length
3
1
Attribute
h
h
Description
Function Code
Return Code
This function verifies the signature on a signed message.
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
PTK EFT MK2
int EFT_EE9006_VerifySignedData (
IN
UCHAR
FM,
IN
KEYSPEC
*PK,
IN
UCHAR
Algorithm,
IN
UCHAR
HashFunction,
IN
EFTBUFFER
*Data,
IN
EFTBUFFER
*Signature);
76
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Generate MD5 Hash
PHW
PSO
PTK EFT MK2
Card Issuance
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
U
Description
Function Code
Function Modifer = 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.
2.
3.
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)
Calculate a hash for sending to the CA with the public key.
Calculate a hash to provide to the ATM operator that confirms the validity of the certificate.
PTK EFT 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] );
77
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Generate SHA Hash
PHW
PSO
PTK EFT MK2
Card Issuance
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
U
Description
Function Code
Function Modifer = 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.
2.
3.
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)
Calculate a hash for sending to the CA with the public key.
Calculate a hash to provide to the ATM operator that confirms the validity of the certificate.
PTK EFT 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
78
UCHAR
EFTBUFFER
BitCount2[8],
*HashResult );
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Generate Key – Diebold
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE9101
FM
D
D
D
U
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifer = 00
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
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
Var
Var
Var
h
h
K-Spec
Key Len
Key Type
Response Content
EE9101
rc
KTB1
rHOST
KKTM
Key token B1
Host random nonce
Key specifier for generated key – as
determined by Key len
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
•
•
2048 length public keys only.
The formats of the encrypted key Block and signature are as described in RSAES-PKCS1-v1_5
and RSASSA-PKCS1-v1_5 in [21].
PTK EFT MK2
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,
IN
UCHAR
KeyType,
OUT
OUT
OUT
© SafeNet, Inc.
EFTBUFFER
EFTBUFFER
KEYSPEC
*KT_B1,
*r_HOST,
*K_KTM);
79
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Verify ATM Response – Diebold
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE9102
FM
KTA2
IHOST
rATM
rHOST
PATM
Response Content
EE9102
rc
D
D
D
U
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifer = 00
Var
Var
Var
Var
Var
h
h
h
h
K-Spec
Length
3
1
Attribute
h
h
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 nonces and identifier provided
in the function request.
NOTES
•
2048 length public keys only.
PTK EFT 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);
80
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
Generate KM – NCR
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE9201
FM
D
D
D
U
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifer = 00
SK-HSM
Var
K-Spec
PK-EPP
Var
K-Spec
Length
3
1
Attribute
h
h
Key specifier for HSM Private Key.
(Format: 82)
Key specifier for EPP Public Key.
(Format: 81)
Description
Function Code
Return Code
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: 13)
Encrypted key Block
Signed encrypted key Block
3
h
NCR Key Verification Value (KVV)
Response Content
EE9201
rc
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 [20].
NOTES
•
2048 length public keys only.
PTK EFT MK2
int EFT_EE9201_GenerateKTM_NCR (
IN
UCHAR
FM,
IN
KEYSPEC
*SK_HSM,
IN
KEYSPEC
*PK_EPP,
OUT
OUT
OUT
OUT
© SafeNet, Inc.
KEYSPEC
EFTBUFFER
EFTBUFFER
UCHAR
*KTM,
*eKTM_PK_EPP,
*sSK_HSM_eKTM_PK_EPP,
KVC_KTM[3] );
81
ProtectHost White Mark II Programmer's Guide
Chapter 9
Remote ATM Initialization Functions
PAGE INTENTIONALLY LEFT BLANK
82
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
84
EE0403
88
EE0404
91
EE0405
93
Receive Initial Session Key
II_KEY_RCV
Rollover Session Key Generation
NI-KEY-GEN
Receive Rollover Session Key
NI_KEY_RCV
© SafeNet, Inc.
83
ProtectHost White Mark II Programmer's Guide
Chapter 10
Interchange Functions
Initial Session Key Generation
II_KEY_GEN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0402
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifer = 00
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
n
eKISnvx(KS)
1
KS-Spec
1
1
1
KVC
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
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.
84
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Key Flags
Chapter 10
Interchange Functions
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 ProtectHost White 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 ProtectHost White 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.
5.
When the Key Flags specify that a KIS is to be generated:
© SafeNet, Inc.
•
If the KIS keys are ProtectHost White 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.
85
ProtectHost White Mark II Programmer's Guide
Chapter 10
Interchange Functions
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, eg. Single
DPK/Double DPK).
Also see point 5 under Details and Restrictions above.
NOTES
•
•
•
•
•
•
•
•
86
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 ProtectHost White
console.
When the AS2805 variant scheme is used, the double length session key encrypted
under KIS is output using CBC.
Please refer to the Console User Guide for directions on how to set options for the
KIS.
This function supercedes function 51, 52, 53.
Bits 13-15 of the key flags are reserved.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 10
Interchange Functions
PTK EFT MK2
int EFT_EE0402_InitialSessionKeyGeneration(
IN
UCHAR
FM,
IN
KEYSPEC
*KIS,
IN
UCHAR
KeyFlags[2],
© SafeNet, Inc.
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] );
87
ProtectHost White Mark II Programmer's Guide
Chapter 10
Interchange Functions
Receive Initial Session Key
II_KEY_RCV
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0403
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifer = 00
KIR-Spec
Var
K-Spec
Key Flags
2
h
Var
Length
3
1
h
Attribute
h
h
Key specifier for KIR
(Formats: 0 - 3, 10, 11, 13, 15)
Key Type indicator / Encryption
mode
Encrypted Session Key
Description
Function Code
Return Code
1
Var
h
K-Spec
3
h
1
eKIRnvx(KS)
Response Content
EE0403
rc
n
KS-Spec
1
1
1
KVC
D
D
D
D
Number of following key sets.
Key specifier for Session Key
(Formats: 10, 11)
Key Verification Code
This set of fields will occur ‘n’ times.
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.
88
FM
= 00. Must be set to zero.
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Key Flags
Chapter 10
Interchange Functions
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 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 ProtectHost White 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:
© SafeNet, Inc.
•
If the KIR keys are ProtectHost White 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.
89
ProtectHost White Mark II Programmer's Guide
Chapter 10
Interchange Functions
Failure caused due to any of the previous 3 occurrences will result in error 0x0C (Inconsistent
request fields) being returning as the return code.
6.
When the Key Flags specify that a new KIR is included in the set this new KIR is encrypted with
the old KIR (KIR-Spec). The encryption mode depends upon the Key Flags mode bit.
Error conditions
The following settings for the 'Key Flags' field will result in a Return Code of 0C.
1. A request for a double-length key to be re-encrypted, though the KIR indicated in the request is a
single-length key
2.
A request to re-encrypt a DPK, though this is disabled for the (HSM-stored) KIR.
3.
A request to re-encrypt a single- and double-length key of same type.
4.
A reserved bit not set to zero.
NOTES
•
•
•
•
•
•
•
•
The encryption mode for eKIRnvx(KS) and KS-Spec is ECB unless otherwise specified.
This function will check the length of KIRn and use the appropriate encryption method.
When there is no variant scheme chosen for the KIR, this function will automatically
disable the ability to generate a DPK. This part of the function can be manually enabled
from the console by selecting “Enable function for receiving of data keys” under the KIR
Options dialog.
The AS2805 variant for KIR is chosen during key input at the ProtectHost White 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.
PTK EFT 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,
90
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]);
(
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 10
Interchange Functions
Rollover Session Key Generation
NI-KEY-GEN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0404
FM
Key Flags
1
KSn Spec
Response Content
EE0404
rc
n
eKSn(KSn+1)
1
KSn+1 Spec
1
1
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
Description
Function Code
Function Modifer = 00
Key Type indicator / Encryption
mode
Key Specifier for Session Key
(Formats: 10, 11)
Description
Function Code
Return Code
Number of following key sets
Encrypted Session Key
Key Specifier for Session Key
(Formats: 10, 11)
Key Verification Code
This set of fields will occur ‘n’ times.
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.
91
ProtectHost White Mark II Programmer's Guide
Chapter 10
Interchange Functions
FM
= 00. Must be set to zero.
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.
PTK EFT MK2
int EFT_EE0404_RolloverSessionKeyGeneration (
IN
UCHAR
FM,
IN
UCHAR
KeyFlags[2],
IN
KEYSPEC
*KSi1,
_IN
KEYSPEC
*KSi2,
_IN
KEYSPEC
*KSi3,
92
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] );
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 10
Interchange Functions
Receive Rollover Session Key
NI_KEY_RCV
PHW
PSO
PTK EFT MK2
Card Issuance
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
1
KVC
D
D
D
D
Description
Function Code
Function Modifer = 00
Key Type indicator / Encryption
mode
Key specifier for Session Key
(Formats: 10, 11)
Encrypted Session Key
Description
Function Code
Return Code
Number of following key sets
Key Specifier for Session Key
(Formats: 10, 11)
Key Verification Code
These fields will occur ‘n’ times.
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
= 00. Must be set to zero.
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.
© SafeNet, Inc.
93
ProtectHost White Mark II Programmer's Guide
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
Chapter 10
Interchange Functions
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.
PTK EFT MK2
int EFT_EE0405_ReceiveRolloverSessionKey(
IN
UCHAR
FM,
IN
UCHAR
KeyFlags[2],
IN
KEYSPEC
*KSi1,
IN
EFTBUFFER
*eKS_KSi1,
94
_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]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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: 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.
Summary of PIN Management Functions
© SafeNet, Inc.
Function Name
Function Code
Page
CLR-PIN-ENCRYPT
EE0600
97
MIGRATEPIN
EE0601
98
PIN-TRAN-2
EE0602
100
PIN-VER-IBM-MULTI
EE0603
102
PIN-TRAN-3624
63
104
95
ProtectHost White Mark II Programmer's Guide
96
Chapter 11
PIN Management Functions
KB-PIN-VER
64
105
VAR-KB-PIN-VER
69
106
PIN-OFF
EE0604
107
PIN-FROM-OFF
EE0609
109
Generate KM-encrypted PIN
EE0640
111
Print a KM-encrypted PIN
EE0641
112
Verify a PIN Using KM-encrypted PIN
EE0642
114
Translate a PIN from PPK to LMK
EE0643
115
Migrate PIN
EE0644
116
IT-PVK-EXPORT
EF0210
117
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PIN Encryption
CLR-PIN-ENCRYPT
PHW (see note)
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0600
FM
PIN-Len
PIN
ANB
PPK-Spec
Response Content
EE0600
rc
ePPK(PIN)
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
1
Var
6
Var
h
d
d
K-Spec
Length
3
1
Attribute
h
h
Number of digits in PIN field
Clear PIN
Account Number Block
Key specifier for PPK
(Formats: 0 - 3, 10, 11, 20, 90)
Description
Function Code
Return Code
8
h
D
D
D
U
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, 20 or 90).
ANB
12 PAN digits of the Account Number Block used to format the
ANSI PIN Block.
NOTES
This function is not included as standard. It will only be available if selected as an order time
option when purchasing your ProtectHost White. Please contact SafeNet if you require this
functionality or further details.
PTK EFT 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]);
97
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
MIGRATEPIN
PHW
PSO
PTK EFT MK2
Card Issuance
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
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 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.
98
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PTK EFT MK2
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.
99
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PIN Translation
PIN-TRAN-2
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0602
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
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
8
h
Response Content
EE0602
rc
ePPKo(PIN)
D
D
D
D
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. PIN Format 02 will be used for input only.
PFo
specifies the output PIN Block format and supports PIN formats: 01, 03, 08,
09, 10, 11, 12, and 13. The following restriction applies: formats 08 (Docutel),
09 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.
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.
NOTE
This function includes all the capabilities of the following existing functions, and therefore
supersedes the following:
PIN- TRAN (60), D51-PIN-TRAN (65), PIN-TRAN-1 (94), PIN-TRAN-2 (95).
100
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PTK EFT MK2
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 19.
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 envoked 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 19. 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 <29>, 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.
101
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PIN Verification
PIN-VER-IBM-MULTI
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0603
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
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, 13, 14)
Validation Data
Existing offset for the PIN
PIN Check Length (04 - 12)
Description
Function Code
Return Code
Validation Data
Offset
Check-Len
Response Content
EE0603
rc
D
D
D
D
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 double-length
HSM-stored or host-stored key.
PF
Supports PIN formats: 01, 02, 03, 08, 09, 10, 11, and 13.
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.
NOTE
This function includes all the capabilities of the following existing functions, and therefore supersedes the
following:
PIN-VER (61), PIN-VER-PP (62), D51-PIN-VER (66), VAR-PIN-VER (67), VAR-PIN-VER-PP (68).
102
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PTK EFT 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.
103
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PINKEY PIN Translation
PIN-TRAN-3624
PHW
PSO
PTK EFT MK2
Card Issuance
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
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 an ProtectHost White stored PIN Verification Key (PVK).
104
PP-PIN
is the PIN/PAD formatted PIN Block. It must be supplied encrypted by an
ProtectHost White 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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
Base Key PIN Verification
KB-PIN-VER
PHW
PSO
PTK EFT MK2
Card Issuance
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
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 an ProtectHost White 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.
© SafeNet, Inc.
105
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
Base Key PIN Verification - Variable Length
VAR-KB-PIN-VER
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
69
Length
1
Attribute
h
PVK-Index
KTM-Index
eKTM(AS-PIN)
1
1
8
d
d
B64
8
6
1
6
Length
1
1
h
h
h
h
Attribute
h
h
PAN
ANB
CHKLEN
Offset
Response Content
69
rc
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.
See Appendix A, for a more detailed overview of the PIN verification procedure.
106
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PIN Offset Generation
PIN-OFF
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0604
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
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, 13,14)
Validation Data
Description
Function Code
Return Code
6
1
h
h
Validation Data
Response Content
EE0604
rc
Offset
PINLEN
D
D
D
D
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 double-length
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.
NOTE
This function includes all the capabilities of the following existing functions, and therefore
supersedes the following
PIN-OFF-AS (6A), PIN-OFF-PP (6B)
© SafeNet, Inc.
107
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PTK EFT 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);
108
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
PIN-FROM-OFF
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0609
FM
D
U
D
D
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
Key specifier for PVK/DT used in the
regeneration of the reference PIN.
(Formats: 0 - 3, 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
8
x
Response Content
EE0609
rc
ePPK(PIN)
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 Host-stored
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.
PPK
PPK-Spec may be key specifier formats: HSM-stored (0-3) and
Host-stored 11 and 13. When the key specifier format is Host-stored
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
109
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
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.
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.
PTK EFT 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
110
UCHAR ePPK_PIN[8]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
Generate KM-encrypted PIN
PHW
PSO
PTK EFT MK2
Card Issuance
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
U
This function generates a random PIN of the specified length and creates a format 1A key specifier,
as defined in Chapter 2.
PTK EFT MK2
int EFT_EE0640_GEN_KM_ENC_PIN(
IN
UCHAR
FM,
IN
UCHAR
PINLen,
IN
UCHAR
ANB[6],
OUT
© SafeNet, Inc.
KEYSPEC
*eKM_PIN);
111
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
Print a KM-encrypted PIN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0641
FM
PIN-Spec
ANB
PAN
Data Sets
Line No
Column No
Data
Response Content
EE0641
rc
D
U
D
U
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
6
8
h
h
1
1
1
Var
h
h
h
h
Length
3
1
Attribute
h
h
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.
PTK EFT MK2
int EFT_EE0641_Print_eKMPin(
IN
UCHAR
FM,
IN
KEYSPEC
*eKM_PIN,
IN
UCHAR
ANB[6],
IN
UCHAR
PAN[8],
112
IN
UCHAR
DataSets,
_IN
_IN
_IN
UCHAR
UCHAR
EFTBUFFER
*LineNo1,
*ColumnNo1,
*Data1,
_IN
_IN
_IN
UCHAR
UCHAR
EFTBUFFER
*LineNo2,
*ColumnNo2,
*Data2,
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
© SafeNet, Inc.
_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);
Chapter 11
PIN Management Functions
113
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
Verify a PIN Using KM-encrypted PIN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0642
FM
ePPK(PIN)
PPK-Spec
PF
ANB
PIN-Spec
Response Content
EE0642
rc
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
8
Var
x
K-Spec
1
h
6
Var
h
K-Spec
Length
3
1
Attribute
h
h
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
D
D
D
U
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.
PTK EFT 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);
114
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
Translate a PIN from PPK to LMK
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0643
FM
ePPK(PIN)
PPK-Spec
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
8
Var
x
K-Spec
1
h
6
Length
3
1
h
Attribute
h
h
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
Var
K-Spec
PF
ANB
Response Content
EE0643
rc
PIN-Spec
D
D
D
U
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.
PTK EFT 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);
115
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
Migrate PIN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0644
FM
PIN-Spec
ANB
Response Content
EE0644
rc
PIN-Spec
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
6
Length
3
1
h
Attribute
h
h
KM-encrypted PIN Block (old KM)
(Format: 1A)
Account Number Block
Description
Function Code
Return Code
Var
K-Spec
D
D
D
U
KM-encrypted PIN Block (current KM)
(Format: 1A)
This function re-encrypts a KM-encrypted PIN from the old KM to the current KM.
PTK EFT MK2
int EFT_EE0644_Migrate_eKMPin(
IN
UCHAR
FM,
IN
KEYSPEC
*eKM_PINi,
IN
UCHAR
ANB[6],
OUT
116
KEYSPEC
*eKM_PINo);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 11
PIN Management Functions
IT-PVK-EXPORT
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EF0210
FM
PVK-Spec
Mode
KTM-Spec
Response Content
EF0210
rc
eKTM(PVK)
KVC
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
1
h
Var
K-Spec
Length
3
1
Attribute
h
h
Key specifier for PVK
(Formats: 0 - 3)
Encryption Method
10 = ECB
11 = Reserved
12 = Reserved
Key specifier for KTM
(Formats: 0 - 3, 10, 11)
Description
Function Code
Return Code
Var
3
h
h
U
D
D
U
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.
PTK EFT 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.
117
ProtectHost White Mark II Programmer's 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
123
OBM GenerateRandomNumber
EE3001
124
OBM Verify PIN – RSA-encrypted, 3624 Offset
EE3002
125
OBM Change PIN – RSA-encrypted, 3624 Offset
EE3003
126
OBM SetPassword RSAEncrypted TPV
EE3004
128
OBM VerifyPassword RSAEncrypted TPV
EE3005
129
OBM ChangePassword RSAEncrypted TPV
EE3006
130
OBM PrintPassword
EE3008
131
OBM MigratePIN OffsetToTPV
EE3009
133
OBM GetPrintToken
EE3016
134
OBM GenerateRandomPIN
EE3017
135
OBM PrintEncryptedPIN
EE3018
136
OBM Translate PIN – RSA-encrypted, PPK
EE3019
138
OBM Set PIN – PPK-encrypted, TPV
EE3020
139
Licensing Requirements
Please note that the Online Banking Module functions documented in this chapter are only available
to licenced users and are otherwise disabled. Eracom Support can assist you to purchase a license and
to enable these functions. To contact Eracom Support use the contact details provided in the Preface
to this Programmers Guide.
Online Banking Module Password Restrictions
User passwords may consist of alpha-numeric characters, i.e. characters in the following ranges:
0 – 9 A – Z a – z.
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.
© SafeNet, Inc.
119
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
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
Function
Code
OBM SetPassword RSAEncrypted TPV
EE3004
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 ProtectHost White stored (HSMstored) 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.
120
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
EPB Processing Unit
Field Content
Length
Attribute
Var
K-Spec
SK-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.
C
Var
h
RSA-encrypted PIN Block.
P
Var
h
PKCS#1 parameter string
RN
Var
h
Random Number
Pre-requisites: None
Process:
Decrypt and decode the RSA-encrypted PIN Block.
Result:
Error Code or Plaintext PIN Block (M).
Processing steps
1.
2.
3.
4.
5.
6.
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.
Decrypt the RSA-encrypted PIN Block, C, using SK.
Decode the resulting PIN Block, in accordance with PKCS #1 and using parameter string P, and
thereby recovering the message M.
Check that the header byte is equal to 1 or 2.
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.
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.
© SafeNet, Inc.
121
ProtectHost White Mark II Programmer's Guide
Field Content
KTPV-Spec
Chapter 12
Online Banking Module Functions
Length
Attribute
Description
Var
K-Spec
KTPV used to encrypt the hashed PIN or
formatted PIN Block. Or zero-length
field if no encryption
(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
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 right 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.
122
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM GetPublicKey()
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
Request Content
EE3000
FM
PK-Spec1
Response Content
EE3000
rc
PK-Spec2
PVC
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
Length
3
1
Attribute
h
h
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
Var
K-Spec
8
h
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 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.
PTK EFT MK2
int EFT_EE3000_OBM_GetPublicKey(
IN
UCHAR
FM,
IN
KEYSPEC
*PK1,
OUT
OUT
© SafeNet, Inc.
KEYSPEC
UCHAR
*PK2,
PVC[8]);
123
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM GenerateRandomNumber
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
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
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.
PTK EFT MK2
int EFT_EE3001_OBM_GenerateRandomNumber(
IN
UCHAR
FM,
IN
UCHAR
Length,
OUT
124
EFTBUFFER
*RandomNumber);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM Verify PIN – RSA-encrypted, 3624 Offset
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
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
Description
Function Code
Function Modifier = 00
Decrypt and decode RSA-encrypted PIN
Block
Key specifier for PVK and Decimalization
Table (Formats: 0 - 3, 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.
2.
3.
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.
Calculate the reference PIN, using the PVK and Decimalization Table indicated by PVK-Spec,
Validation Data and Offset.
Compare the reference PIN with the transaction PIN (from recovered PIN Block, M). Return the
result of the comparison in Return Code.
PTK EFT 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.
125
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM Change PIN – RSA-encrypted, 3624
Offset
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
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
Description
Function Code
Function Modifier = 00
Decrypt and decode RSA-encrypted PIN
Block
Key specifier for PVK and Decimalization
Table (Formats: 0 – 3, 13, 14)
Customer data – usually part of the PAN
PIN offset data
Key specifier for PVK and Decimalization
Table (Formats: 0 – 3, 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.
2.
3.
4.
5.
126
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.
Calculate the reference PIN, using the PVK and Decimalization Table indicated by PVK-Spec1,
Validation Data1 and Offset1.
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.
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.
Return the PIN offset in Offset2.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
PTK EFT MK2
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]);
127
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM SetPassword RSAEncrypted TPV
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
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
Var
h
Reference Hash
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.
PTK EFT 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
128
EFTBUFFER
*ReferenceTPV);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM VerifyPassword RSAEncrypted TPV
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
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
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.
PTK EFT 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.
129
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM ChangePassword RSAEncrypted TPV
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
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.
PTK EFT 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
130
EFTBUFFER
*ReferenceTPV2);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM PrintPassword
D
PHW
PSO
D
PTK EFT MK2
Card Issuance
Request Content
EE3008
FM
Length
3
1
Attribute
h
h
Password Type
1
h
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.
Password Length
Description
Function Code
Function Modifier = 00
1
h
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
CTPV
Data
Response Content
EE3008
rc
Reference TPV
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
ProtectHost White 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 ProtectHost White Mark II Console User
Guide.
PTK EFT MK2
int EFT_EE3008_OBM_PrintPassword(
IN
UCHAR
*ESMID,
IN
UCHAR
FM,
IN
UCHAR
PasswordType,
IN
UCHAR
PasswordLength,
IN
UCHAR
AlgorithmID,
© SafeNet, Inc.
131
ProtectHost White Mark II Programmer's Guide
132
Chapter 12
Online Banking Module Functions
IN
IN
IN
IN
EFTBUFFER
EFTBUFFER
KEYSPEC
UCHAR
*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);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM MigratePIN OffsetToTPV
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
Request Content
EE3009
FM
PVK-Spec
Validation Data
Offset
Password Length
CTPV
Response Content
EE3009
rc
Reference TPV
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
8
h
6
1
Struct
Length
3
1
h
h
PU
Attribute
h
h
Key specifier for PVK and Decimalization
Table. (Format 0 –3, 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
Var
h
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.
PTK EFT 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);
133
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM GetPrintToken
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
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
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
PTK EFT MK2
int EFT_EE3016_OBM_GetPrintToken(
IN
UCHAR
*ESMID,
OUT
134
UCHAR
IN
UCHAR FM,
PrintToken[8]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM GenerateRandomPIN
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
Request Content
EE3017
FM
Pin Type
Length
3
1
Attribute
h
h
1
h
PIN Length
CTPV
1
Struct
Print Token
8
PPK-Spec
Response Content
EE3017
rc
Var
Length
3
1
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
h
CTPV
Processing
Unit
h
Print Token of the Remote PHW which
will be printing out this generated PIN
K-Spec
Key Specifier for PPK
(Formats: 0 - 3)
Attribute Description
h
Function Code
h
Return Code
ePPK(OBM Print PIN
Block)
Var
h
Encrypted OBM Print PIN Block
Reference TPV
Var
h
Transformed PIN Value
This function generates a random (numeric or alpha-numeric) PIN and returns:
1) a reference TPV for storage and subsequent verification of the PIN
2) an encrypted OBM Print PIN Block (PIN Block = Print Token + PIN Block) to be printed in a
remote location
The Random PIN Generation adheres to the password restrictions as described in the Online Banking
Module Password Restrictions section at the beginning of this chapter.
PTK EFT 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);
135
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM PrintEncryptedPIN
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
Request Content
EE3018
FM
Length
3
1
Attribute
h
h
PIN Length
1
h
PPK-Spec
Var
K-Spec
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.
Line No1
1
h
The line number for the data to be printed
at.
Column No1
1
h
The column number for the data to be
printed at.
Var
Length
3
1
h
Attribute
h
h
Data1
Response Content
EE3018
rc
1
The data to be printed.
Description
Function Code
Return Code
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.
136
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
PTK EFT 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);
137
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM Translate PIN – RSA-encrypted, PPK
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
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
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, 03, 08, 09, 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 PHW console's
function control menu whether this function is enabled or disabled.
PTK EFT 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
138
EFTBUFFER
*ePPKo_PIN);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
OBM Set PIN – PPK-encrypted, TPV
PHW
D
PSO
PTK EFT MK2
D
Card Issuance
Request Content
EE3020
FM
ePPK(PIN)
PPKi-Spec
PFi
ANB
CTPV
Response Content
EE3020
rc
Reference TPV
Length
2
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
8
Var
x
K-Spec
1
h
6
Struct
Length
2
1
h
PU
Attribute
h
h
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
Var
h
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 PHW console's function control menu whether this function is enabled or
disabled.
PTK EFT 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
© SafeNet, Inc.
EFTBUFFER
*ReferenceTPV);
139
ProtectHost White Mark II Programmer's Guide
Chapter 12
Online Banking Module Functions
THIS PAGE INTENTIONALLY LEFT BLANK
140
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
Chapter 13
Visa Functions
The Visa option specified here is required in an ProtectHost White 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 ProtectHost White
Console Operator’s Guide.
Refer to Visa 3DES Support on page 146 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
147
PVV- CALC-3624
EE0606
149
PVV-CALC
EE0607
150
DIEBOLD_PIN_VER
EE0614
152
DIEBOLD_PIN_OFF
EE0616
154
PIN-TRANS-SEED-DES
EE0615
156
CVV- GENERATE
EE0802
158
CVV- VERIFY
EE0803
159
Visa Overview
Visa provides a world-wide network which allows the cards of a participating member institution to
be used in the EFT terminals of other participating members. In such a transaction, Visa refers to the
institution which owns the EFT terminal as the Acquirer. The network performs the necessary
switching between Acquirer and Issuer.
Additionally, Visa provides an optional PIN Verification Service (PVS) which obviates the
requirement to switch the transaction through to the Issuer. The PVS is performed at the Visa
Network Central host. This service involves the PVV method of PIN Verification. The method may
also be used by the Issuer for verification of the PIN in an 'on-us' transaction.
Members of Visa International must comply with Visa's requirements for Card Verification Values
(CVV).
Network Requirements
The routing of a transaction from Acquirer to Issuer involves two encryption zones:
-
The Acquirer zone extends between the Acquirer host and a Network Central host. In this zone
the PIN is encrypted by an Acquirer Working Key (AWK).
-
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).
© SafeNet, Inc.
141
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
The translation of the PIN encryption key (and of the PIN Block format, if necessary) occurs in an
ProtectHost White 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
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.]
142
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
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 ProtectHost White cater for both these situations.
Key Management Operations
The Visa key management operations are performed using the ProtectHost White console.
The following Keys used in the ProtectHost White 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.
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:
© SafeNet, Inc.
143
ProtectHost White Mark II Programmer's Guide
1.
2.
3.
Chapter 13
Visa Functions
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 ProtectHost White 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 ProtectHost White 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 ProtectHost White 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 ProtectHost White 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 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.
144
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
PVK Pair Storage
The ProtectHost White 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 ProtectHost White 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 ProtectHost White supports PIN Blocks encrypted by (short-term)
session keys known as PIN Protect Keys (PPK). The following re-encryptions are supported:
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.
© SafeNet, Inc.
145
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
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 ProtectHost White 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
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
146
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
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
PVV-VER
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0605
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
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
TSP12
PVV
Response Content
EE0605
rc
D
D
D
D
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 double-length
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.
NOTE
•
© SafeNet, Inc.
This function includes all the capabilities of the following existing functions and hence
supersedes 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)
147
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
PTK EFT 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]);
148
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
PVV- CALC-3624
D
D
D
D
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0606
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
PVK-Spec
Var
K-Spec
Validation Data
Offset4
PVVK-Spec
8
2
Var
h
d
K-Spec
6
Length
3
1
h
Attribute
h
h
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
2
x
TSP12
Response Content
EE0606
rc
PVV
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 supersedes the following:
PVV-GEN-1 (90), PIN-GEN-2 (96).
PTK EFT 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]);
149
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
PVV-CALC
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0607
FM
ePPK(PIN)
PPK-Spec
PF
ANB
PVVK-Spec
TSP12
Response Content
EE0607
rc
PVV
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
8
Var
x
K-Spec
1
h
6
Var
d
K-Spec
6
Length
3
1
h
Attribute
h
h
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
2
x
D
D
D
D
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.
NOTE
•
This function includes all the capabilities of the following existing functions, and thereby
supersedes the following:
PVV-CHANGE (9A)
150
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
PTK EFT 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]);
151
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
Diebold Table Support
DIEBOLD_PIN_VER
PHW
PSO
PTK EFT MK2
Card Issuance
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
Length
1
1
Attribute
h
h
PF
Response Content
EE0614
rc
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).
152
PF
Pin Format, which may take one of the following values:
01h1
PIN-TRANS format 01
ISO 9564-1 format 0
AS2805 Part 3 format 0
03h
PIN-TRANS format 3
08h
Docutel 5100 format
10h
same as 01 above
11h1
ISO 9564-1 format 0
13h1
ISO 9564-1 format 3
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
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
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.
PTK EFT 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.
153
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
DIEBOLD_PIN_OFF
PHW
PSO
PTK EFT MK2
Card Issuance
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
Length
1
1
2
Attribute
h
h
d
PF
Response Content
EE0616
Rc
Offset
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).
154
PF
Pin Format, which may take one of the following values:
01h1
PIN-TRANS format 01
ISO 9564-1 format 0
AS2805 Part 3 format 0
03h
PIN-TRANS format 3
08h
Docutel 5100 format
10h
same as 01 above
11h1
ISO 9564-1 format 0
13h1
ISO 9564-1 format 3
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
AlgID
A number from 0 to 255 that is an input into the pin verification algorithm.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
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.
PTK EFT 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]);
155
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
SEED Translation
PIN-TRANS-SEED-DES
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0615
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
Var
x
K-Spec
1
h
ANB
PFo
Var
1
h
h
PPKo-Spec
Var
K-Spec
Length
3
1
Attribute
h
h
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
Var
h
ePPKi(PIN)
PPKi-Spec
PFi
Response Content
EE0615
rc
ePPKo(PIN)
D
U
D
D
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.
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)
PIN Block encrypted using the SEED algorithm by PPKi. This Var
field must be 16 bytes in length.
NOTES
156
•
For key specifier formats, refer to Chapter 2 Function Construction.
•
For information on the SEED algorithm see the Glossary.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
PTK EFT 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);
157
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
CVV- GENERATE
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0802
FM
CVK-Spec
CVV-Data
Response Content
EE0802
rc
CVV
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
16
Length
3
1
h
Attribute
h
h
Card Verification Key specification
(Formats: 0 - 3, 11, 13)
Card Verification Value Data
Description
Function Code
Return Code
2
h
D
D
D
D
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.
PTK EFT MK2
int EFT_EE0802_CVVGenerate (
IN
UCHAR
FM,
IN
KEYSPEC
*CVK_Spec,
IN
UCHAR
CVV_Data[16],
OUT
158
UCHAR
CVV[2]
);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
CVV- VERIFY
D
D
D
D
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0803
FM
CVK-Spec
CVV-Data
CVV
Response Content
EE0803
rc
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
16
2
Length
3
1
h
h
Attribute
h
h
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.
PTK EFT MK2
int EFT_EE0803_CVVVerify(
IN
UCHAR
FM,
IN
KEYSPEC
*CVK_Spec,
IN
UCHAR
CVV_Data[16],
IN
UCHAR
CVV[2]);
© SafeNet, Inc.
159
ProtectHost White Mark II Programmer's Guide
Chapter 13
Visa Functions
THIS PAGE INTENTIONALLY LEFT BLANK
160
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
162
MAC_GEN_FINAL
EE0701
164
MAC_VER_FINAL
EE0702
166
KTM-MAC-GEN
73
168
161
ProtectHost White Mark II Programmer's Guide
Chapter 14
MAC Management Functions
MAC Generation
MAC_GEN_UPDATE
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0700
FM
Alg
Length
3
1
Attribute
h
h
1
h
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.
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
162
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 14
MAC Management Functions
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
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.
PTK EFT 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]);
163
ProtectHost White Mark II Programmer's Guide
Chapter 14
MAC Management Functions
MAC_GEN_FINAL
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0701
FM
Alg
Length
3
1
Attribute
h
h
1
h
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.
164
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
FM
= 00. Must be set to zero.
Alg
Specifies the MACing algorithm to use.
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
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.
PTK EFT 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);
165
ProtectHost White Mark II Programmer's Guide
Chapter 14
MAC Management Functions
MAC_VER_FINAL
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0702
FM
Alg
Length
3
1
Attribute
h
h
1
h
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.
166
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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.
PTK EFT 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.
167
ProtectHost White Mark II Programmer's Guide
Chapter 14
MAC Management Functions
Terminal Master Key MAC Generation
KTM-MAC-GEN
PHW
PSO
PTK EFT MK2
Card Issuance
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
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.
168
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
169
DECIPHER_2
EE0801
172
ENCIPHER_3
EE0804
174
DECIPHER_3
EE0805
176
ENCIPHER-KTM1
EE0806
178
B-ENCIPHER-ECB
84
180
B-DECIPHER-ECB
85
181
169
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
ENCIPHER_2
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0800
FM
DPK-Spec
CM
ICV
Data
Response Content
EE0800
rc
OCV
eDPK(Data)
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
1
h
8
Var
Length
3
1
h
h
Attribute
h
h
Key specifier for DPK
(Formats: 0 - 3, 10, 11, 13, 51)
Cipher Mode
00 = ECB
01 = CBC
Input Chaining Value
Data to be enciphered
Description
Function Code
Return Code
8
Var
h
h
D
D
D
D
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.
170
DPK-Spec
Key specifier incorporating a single or double length host-stored or HSMstored 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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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.
PTK EFT 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 ) ;
171
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
DECIPHER_2
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0801
FM
DPK-Spec
CM
ICV
eDPK(Data)
Response Content
EE0801
rc
OCV
Data
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
1
h
8
Var
Length
3
1
h
h
Attribute
h
h
Key specifier for DPK
(Formats: 0 - 3, 10, 11, 13, 51)
Cipher Mode
00 = ECB
01 = CBC
Input Chaining Value
Cipher text
Description
Function Code
Return Code
8
Var
h
h
D
D
D
D
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.
172
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.
Data
Deciphered plaintext data.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
NOTES
•
This function supercedes functions 81, 83.
•
When the function modifier is missing, the function returns error code 24, missing function
code.
PTK EFT 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);
173
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
ENCIPHER_3
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0804
FM
DPK-Spec
CM
ICV
Data
Response Content
EE0804
rc
OCV
eDPK(Data)
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
1
h
Var
Var
Length
3
1
h
h
Attribute
h
h
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
Var
Var
h
h
D
U
D
D
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.
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.
CM
ICV
OCV
174
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Data
Chapter 15
Data Ciphering Functions
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.
NOTES
•
For information on the SEED algorithm see the Glossary.
•
When the = 00 is missing, the function returns error code 24, missing function code.
PTK EFT 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 );
175
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
DECIPHER_3
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0805
FM
DPK-Spec
CM
ICV
eDPK(Data)
Response Content
EE0805
rc
OCV
Data
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
1
h
Var
Var
Length
3
1
h
h
Attribute
h
h
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
Var
Var
h
h
D
U
D
D
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
message or file using a multi-call decipherment, the value in this field
should be used as the ICV in the next call.
CM
ICV
eDPK(Data)
OCV
176
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Data
Chapter 15
Data Ciphering Functions
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.
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.
PTK EFT 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);
177
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
ENCIPHER-KTM1
PHW
PSO
PTK EFT MK2
Card Issuance
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
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
eDPK(KTM)
178
= 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.
KTM key encrypted with DPK according to the algorithm specified.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
NOTE
1.
2.
3.
4.
This function is an insecure one as it allows KTMs to be encrypted by DPKs. Its use is not
recommended by Eracom.
This function currently supports SEED encryption using ECB mode. It does not support
SEED CBC mode.
This function is not included as standard. It will only be available if selected as an order time
option when purchasing a Protecthost White. Please contact Eracom if you require this
functionality or further details.
For information on the SEED algorithm see the Glossary.
PTK EFT 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);
179
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
3624 B-Key Enciphering
B-ENCIPHER-ECB
PHW
PSO
PTK EFT MK2
Card Issuance
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
U
U
U
Data encrypted under Base Key
This function encrypts the supplied DATA under the B- key (BK) of the ProtectHost White stored
3624 Terminal Key Set as indicated by the specified index (TKSI), using the DES in Electronic Code
Book mode.
180
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
3624 B-Key Deciphering
B-DECIPHER-ECB
PHW
PSO
PTK EFT MK2
Card Issuance
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
U
U
U
Clear Data
This function decrypts the supplied encrypted DATA using the B-key (BK) of the ProtectHost White
stored 3624 Terminal Key Set as indicated by the specified index (TKSI), and using the DES in
Electronic Code Book mode.
© SafeNet, Inc.
181
ProtectHost White Mark II Programmer's Guide
Chapter 15
Data Ciphering Functions
THIS PAGE INTENTIONALLY LEFT BLANK
182
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 16
MasterCard Functions
Chapter 16
MasterCard Functions
The MasterCard support option provides the additional facilities required in the ProtectHost White 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 184 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
185
MT-KPE-RCV
A1
186
MT-PIN-TRAN
A2
187
MT-PIN-VER
A3
188
MT_PIN_VER_PVV
A7
189
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 ProtectHost White 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.
Consistent with existing ProtectHost White practice, long-term keys are stored within ProtectHost
White key memory, whereas short-term (session) keys are stored encrypted in the host computer. The
© SafeNet, Inc.
183
ProtectHost White Mark II Programmer's Guide
Chapter 16
MasterCard Functions
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 ProtectHost
White 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
MT-KPE-RCV
MT-PIN-VER
MT-PIN-TRAN
184
Replacement functions
II-Key-Gen
II-Key-Rcv
PIN Verify
PIN Translate
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 16
MasterCard Functions
MT-KPE-GEN
PHW
PSO
PTK EFT MK2
Card Issuance
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
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.
PTK EFT 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]);
185
ProtectHost White Mark II Programmer's Guide
Chapter 16
MasterCard Functions
MT-KPE-RCV
PHW
PSO
PTK EFT MK2
Card Issuance
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
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 ProtectHost White
PIN management functions. In this case, the KPE is equivalent to the ProtectHost White notation of
the PPK.
PTK EFT MK2
int EFT_A1_MT_KPE_Rcv(
IN
UCHAR MTIndex,
IN
UCHAR eKEKn_KPE[8],
OUT
OUT
186
UCHAR eKMv1_KPE[8],
UCHAR KCV[2]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 16
MasterCard Functions
MT-PIN-TRAN
PHW
PSO
PTK EFT MK2
Card Issuance
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)
D
U
D
U
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 ProtectHost White 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 ProtectHost White stored PIN Encryption Key.
This function is provided for use by an acquirer employing manual key management.
PTK EFT 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]);
187
ProtectHost White Mark II Programmer's Guide
Chapter 16
MasterCard Functions
MT-PIN-VER
PHW
PSO
PTK EFT MK2
Card Issuance
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
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.
PTK EFT 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]);
188
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 16
MasterCard Functions
MT_PIN_VER_PVV
PHW
PSO
PTK EFT MK2
Card Issuance
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
D
U
D
U
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.
PTK EFT 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.
189
ProtectHost White Mark II Programmer's Guide
Chapter 16
MasterCard Functions
THIS PAGE INTENTIONALLY LEFT BLANK
190
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 17
American Express Functions
Chapter 17
American Express Functions
This section defines the ProtectHost White functionality for generating Card Security Codes as
defined by American Express.
Note: Refer to Appendix E 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 F 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
193
CREATE_CSCK
A9
194
EXPORT_CSCK
AA
195
IMPORT_CSCK
AB
196
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
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.
© SafeNet, Inc.
191
ProtectHost White Mark II Programmer's Guide
Chapter 17
American Express Functions
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.
192
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 17
American Express Functions
CALC_CSCK
PHW
PSO
PTK EFT MK2
Card Issuance
Request content
A8
CSCK-Spec
CardData
Response content
A8
rc
CSC
Length
1
Attribute
Description
Function code
Var
K-Spec
8
Length
1
1
h
Attribute
h
h
Key specifier for CSCK
(Formats: 0 - 3, 11)
The account Block
Description
Function code
Return code
6
h
D
U
D
D
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.
PTK EFT MK2
int EFT_A8_CalculateCSCK (
IN
KEYSPEC
*CSCK,
IN
UCHAR
CardData [8],
OUT
© SafeNet, Inc.
UCHAR
CSC[6] );
193
ProtectHost White Mark II Programmer's Guide
Chapter 17
American Express Functions
CREATE_CSCK
PHW
PSO
PTK EFT MK2
Card Issuance
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
D
U
D
D
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)
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.
PTK EFT MK2
int EFT_A9_CreateCSCK (
IN
UCHAR
CSCK_storage_indicator,
OUT
OUT
194
KEYSPEC
UCHAR
*CSCK,
KVC[3]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 17
American Express Functions
EXPORT_CSCK
PHW
PSO
PTK EFT MK2
Card Issuance
Request content
AA
Length
1
Attribute
h
Description
Function code
CSCK-Spec
Var
K-Spec
KIS-Spec
Var
K-Spec
Length
1
1
Attribute
h
h
Key specifier for CSCK
(Format: 11)
Key specifier KIS (ZMK).
(Formats: 0 - 3)
Description
Function code
Return code
16
3
h
h
Response content
AA
rc
eKIS(CSCK)
KVC
D
U
D
D
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.
PTK EFT MK2
int EFT_AA_ExportCSCK (
IN KEYSPEC
*CSCK,
IN KEYSPEC
*KIS,
OUT UCHAR
OUT UCHAR
© SafeNet, Inc.
eKIS_CSCK[16],
KVC[3]);
195
ProtectHost White Mark II Programmer's Guide
Chapter 17
American Express Functions
IMPORT_CSCK
PHW
PSO
PTK EFT MK2
Card Issuance
Request content
AB
Length
1
Attribute
h
CSCK-Storage
Indicator
1
h
Var
K-Spec
16
Length
Attribute
1
1
h
h
Var
K-Spec
3
h
KIR-Spec
eKIR(CSCK)
Response
content
AB
rc
CSCK-Spec
KVC
D
U
D
D
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)
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.
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.
PTK EFT MK2
int EFT_AB_ImportCSCK (
IN
UCHAR
CSCK_storage_indicator,
IN
KEYSPEC
*KIR,
IN
UCHAR
eKIR_CSCK[16],
OUT
OUT
196
KEYSPEC
UCHAR
*CSCK,
KVC[3]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 18
PIN Issuance Functions
Chapter 18
PIN Issuance Functions
Summary of PIN Issuance Functions
© SafeNet, Inc.
Function Name
Function Code
Page
PIN-MAIL
E2
200
PIN-GENERATE
EE0E04
202
PIN-PRINT
EE0E05
203
197
ProtectHost White Mark II Programmer's Guide
Chapter 18
PIN Issuance Functions
PIN Issuance Overview
The ProtectHost White’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 ProtectHost White Mark II Console Users
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
ProtectHost White.
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 ProtectHost White
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 ProtectHost White functions.
It is recommended that a static (host stored or ProtectHost White 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).
198
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 18
PIN Issuance Functions
Host Function Example
An example of a host request (using the Eracom 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 Value
3C
E2
09
1234567890123456
04
01
01
01
03
414141
0B
01
04
42424242
0C
3E
© SafeNet, Inc.
Field Name
Start of Message
Function Code
PK-Index
PAN
number of PIN digits
PINTYP
line No of 1st data field
column No of 1st data field
length of 1st data field
contents of 1st data field
line No of 2nd data field
column No of 2nd data field
length of 2nd data field
contents of 2nd data field
BCC
End of Message
199
ProtectHost White Mark II Programmer's Guide
Chapter 18
PIN Issuance Functions
PIN-MAIL
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
E2
PVK-Index
PAN
PIN Len
PIN Type
Line No*
Column No*
Data Len*
Data*
Response Content
E2
rc
Offset
Length
1
Attribute
h
Description
Function Code
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
DATALEN
D
U
D
D
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 ProtectHost White 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.
200
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.
Data Len
This is the length of the Data. It must be greater than zero and must not extend
beyond the end of an envelope line.
Data
This field contains the ASCII data to be printed.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 18
PIN Issuance Functions
Offset
This field consists of 12 digits of offset data. The significant digits are leftjustified in the field.
ESMID
Part of the PTK EFT MK2 function call. The ESMID is a pointer to a NULL
terminated string that identifies the name of the Eracom HSM (ESM) to which
functions are directed. The Eracom HSM name is set using the
wincommsconfig utility provided as part of the PTK EFT product suite.
PTK EFT 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,
_IN
_IN
_IN
UCHAR
UCHAR
EFTBUFFER
*LineNo10,
*ColumnNo10,
*Data10,
_OUT
UCHAR
offset [6] );
201
ProtectHost White Mark II Programmer's Guide
Chapter 18
PIN Issuance Functions
PIN-GENERATE
PHW
PSO
PTK EFT MK2
Card Issuance
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
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.
PTK EFT MK2
int EFT_EE0E04_GenRandomPIN(
IN
UCHAR
FM,
IN
UCHAR
PINLen,
IN
UCHAR
PFo,
IN
UCHAR
ANB[6],
IN
KEYSPEC
*PPK,
OUT
202
UCHAR
ePPK_PIN[8]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 18
PIN Issuance Functions
PIN-PRINT
D
U
D
D
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0E05
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
8
Var
h
K-Spec
PFi
1
h
ANB
PAN
6
8
h
h
1
1
1
Var
h
h
h
h
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.
Length
1
1
Attribute
h
h
ePPK(PIN)
PPK-Spec
Data Sets
Line No
Column No
Data
Response Content
EE0E05
rc
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 PTK EFT MK2 function call. The ESMID is a pointer to a NULL
terminated string that identifies the name of the Eracom HSM (ESM) to which
functions are directed. The Eracom HSM name is set using the
wincommsconfig utility provided as part of the PTK EFT 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.
© SafeNet, Inc.
203
ProtectHost White Mark II Programmer's Guide
Chapter 18
PIN Issuance Functions
PTK EFT MK2
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],
204
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);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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 D 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
206
EMV_AC_GEN
EE2000
207
EMV_AC_VERIFY
EE2001
208
EMV_DAC_GEN
EE2002
211
EMV_DAC_VERIFY
EE2003
212
EMV_ICC_DN_GEN
EE2004
213
EMV_ICC_DN_VERIFY
EE2005
214
EMV_ARPC_GEN
EE2006
215
EMV_SCRIPT_CRYPTO
EE2007
216
EMV_VERIFY_AC_EMV2000
EF2010
218
EMV_SCRIPT_CRYPTO_VISA
EF2011
221
EMV_GENERATE_ARPC
EF2012
223
EMV_SCRIPT_CRYPTO_EMV2000
EF2013
225
EMV_SCRIPT_CRYPTO_VISA
EF2014
228
EMV_PIN_CHANGE_UNBLOCK_VISA
EF2015
230
EMV_PIN_CHANGE_UNBLOCK
EE2016
233
EMV_PIN_CHANGE_UNBLOCK_EMV_2000
EE2017
235
EMV_VERIFY_AC_GEN_ARPC
EMV_AC_GEN_MULTI EMV_AC_GEN_MULTI
EE2018
237
EE2019
242
205
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
GEN_RANDOM
PHW
PSO
PTK EFT MK2
Card Issuance
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.
D
D
D
D
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.
PTK EFT MK2
int EFT_EE0002_EMVGenRandomNumber(
IN
UCHAR
FM,
IN
UCHAR
Len,
OUT
206
EFTBUFFER
*RAND_NUM);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_AC_GEN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE2000
FM
IMKAC –Spec
APANB
RN
AC-Data
Response Content
EE2000
rc
AC
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
8
8
Var
Length
3
1
h
h
h
Attribute
h
h
Key specifier for IMKAC
(Formats: 0 – 3, 13)
Application PAN Block
Random Number
Application Cryptogram Data
Description
Function Code
Return Code
8
h
D
D
D
D
Application Cryptogram
This function generates an Application Cryptogram (TC, AAC or ARQC) as defined in [1]
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 13 accepted. Support provided for CBC only.
APANB :
Application PAN Block as defined in [1] The HSM performs no checking on
the contents of this field.
RN :
Random number for creating the ICC Session Key as defined in [1] 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 [1] 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 I 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].
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].
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].
PTK EFT 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.
207
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_AC_VERIFY
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE2001
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00, 01 or 04
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
Key specifier for IMKAC
(Formats: 0 - 3, 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
IMKAC-Spec
APANB
RN
AC/CAP Token
D
D
D
D
This function verifies an application cryptogram (TC, AAC or ARQC) as defined in [1]
208
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 13 accepted. Support provided for CBC only.
APANB
Application PAN Block as defined in [Ref.1]. 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]. 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]. This field is 8 bytes in length. This field is present when FM
= 00.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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 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 [31].The CAP Token field contains the bits of the Application Cryptogram
to be verfified 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.
AC-Data
Data used to calculate the TC, AAC or ARQC, as specified in [Ref. 1]. 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 I 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].
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].
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].
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
© SafeNet, Inc.
UCHAR
KEYSPEC
UCHAR
UCHAR
UCHAR
EFTBUFFER
FM,
*IMK_AC,
APANB[8],
RN[8],
AC[8],
*AC_DATA);
209
ProtectHost White Mark II Programmer's Guide
For FM=01 or FM=4
int EFT_EE2001_EMVAcVerify_2(
IN
IN
IN
IN
IN
IN
IN
IN
210
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);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_DAC_GEN
PHW
PSO
PTK EFT MK2
Card Issuance
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, 13)
Application PAN Block
Description
Function Code
Return Code
2
h
Data Authentication Code
D
D
D
D
This function generates a Data Authentication Code (DAC) as defined in [1].
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 13 accepted. Support provided for CBC only.
APANB :
Application PAN Block as defined in [Ref.1]. 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 I 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].
PTK EFT MK2
int EFT_EE2002_EMVDacGen(
IN
UCHAR
FM,
IN
KEYSPEC
*IMK_DAC,
IN
UCHAR
APANB[8],
OUT
© SafeNet, Inc.
UCHAR
DAC[2]);
211
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_DAC_VERIFY
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE2003
FM
IMKDAC –Spec
APANB
DAC
Response Content
EE2003
rc
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
8
2
Length
3
1
h
h
Attribute
h
h
Key specifier for IMKDAC
(Formats: 0 – 3, 13)
Application PAN Block
Data Authentication Code
Description
Function Code
Return Code
D
D
D
D
This function verifies a Data Authentication Code (DAC) as defined in [1].
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 13 accepted. Support provided for CBC only.
APANB :
Application PAN Block as defined in [Ref.1]. The HSM performs no checking
on the contents of this field.
DAC
DAC(Data Authentication Code) calculated by ICC as defined in [1].
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. Derive the DAC using the Issuer Master Key and APANB, according to the method specified in
2.9 of reference [1].
2. Compare the values of the calculated Data Authentication Code and that supplied in DAC.
PTK EFT MK2
int EFT_EE2003_EMVDacVerify(
IN
UCHAR
FM,
IN
KEYSPEC
*IMK_DAC,
IN
UCHAR
APANB[8],
IN
UCHAR
DAC[2]);
212
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_ICC_DN_GEN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE2004
FM
IMKIDN-Spec
APANB
IDN Data
Response Content
EE2004
rc
IDN
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 IMKIDN
(Formats: 0 - 3, 13)
Application PAN Block
ICC Dynamic Number Data
Description
Function Code
Return Code
2
h
D
D
D
D
ICC Dynamic Number
This function generates a ICC Dynamic Number as defined in [ 1].
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 13 accepted. Support provided for CBC only.
APANB :
Application PAN Block as defined in [Ref.1]. The HSM performs no checking
on the contents of this field.
IDN Data :
Data for calculating IDN, as specified in [Ref.1]
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. 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].
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].
NOTE
IDN Data should contain the value which is the ICC Application Transaction
Counter (ATC) and the Unpredictable Number (UN).
PTK EFT 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.
213
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_ICC_DN_VERIFY
PHW
PSO
PTK EFT MK2
Card Issuance
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, 13)
Application PAN Block
Random Number
ICC Dynamic Number
Description
Function Code
Return Code
D
D
D
D
This function verifies a ICC Dynamic Number as defined in [1].
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 13 accepted. Support provided for CBC only.
APANB
Application PAN Block as defined in [Ref.1]. The HSM performs no checking
on the contents of this field.
RN
Random number for calculating data of IDN as defined in [1].
IDN
Calculated ICC Dynamic Number as defined in [Ref.1]
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. 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].
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].
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).
PTK EFT MK2
int EFT_EE2005_EMVIccDnVerify(
IN
UCHAR
FM,
IN
KEYSPEC
*IMK_IDN,
IN
UCHAR
APANB[8],
IN
UCHAR
RN[8],
IN
UCHAR
IDN[2]);
214
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_ARPC_GEN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE2006
FM
IMKAC-Spec
APANB
ARPC-Data
Response Content
EE2006
rc
ARPC
D
D
D
D
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 IMKAC
(Formats: 0 - 3, 13)
Application PAN Block
Authorization Response Cryptogram Data
Description
Function Code
Return Code
8
h
Authorization Response Cryptogram
This function generates an Authorization Response Cryptogram as defined in [1].
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 13 accepted. Support provided for CBC only.
APANB
Application PAN Block as defined in [Ref.1]. 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 [1]
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. 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].
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].
PTK EFT 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]);
215
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_SCRIPT_CRYPTO
PHW
PSO
PTK EFT MK2
Card Issuance
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
Length
3
1
Attribute
h
h
SC
Response Content
EE2007
rc
eSMC(text) Variable
MAC
8
h
h
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, 13)
Key specifier for IMKSMC
(Formats: 0 - 3, 13)
Application PAN Block
Random Number
Plain Text Data
(Must be a multiple of 8 bytes)
Pointer into Script-Data
Script Data
(Must be a multiple of 8 bytes)
Description
Function Code
Return Code
Encrypted data.
Message Authentication Code
This function performs the cryptographic processing required for Secure Messaging as defined in
[Ref. 1]. 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.
216
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 13 accepted. Support provided for CBC only.
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
IMKSMC –Spec
Key specifier which provides access to the IMKSMC.
Formats 0 – 3, and 13 accepted. Support provided for CBC only.
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 [Ref.1]. 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.
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 I 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]. 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].
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 [1].
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].
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.
PTK EFT MK2
PTK EFT 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]);
217
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_VERIFY_AC_EMV2000
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EF2010
FM
Length
3
1
Attribute
h
h
Description
Function Code.
Function Modifier = 00, 01 or 04
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
Key specifier for IMKAC
(Formats: 0 - 3, 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
IMKAC-Spec
PAN Data
IV
H
b
ATC
AC/ CAP Token
D
D
D
D
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 [5].
218
FM
= 00. When the = 00 is set to 00 the Bitmap fieldis are not included. When the
= 00 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 13 accepted. Support provided for CBC only.
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)
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
AC
Application Cryptogram (TC, AAC or ARQC) Calculated by ICC as defined
in Reference [1]. 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 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 [31].The CAP Token field contains the bits of the Application Cryptogram
to be verfified 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.
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
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 I 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].
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].
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].
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.
PTK EFT 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);
© SafeNet, Inc.
219
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
For FM = 01 or FM = 04
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);
220
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_VERIFY_AC_VISA
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EF2011
FM
D
D
D
D
Length
3
1
Attribute
h
h
Description
Function Code.
Function Modifier = 00 or 01
Var
K-Spec
8
8/Var
h
h
AC Data
Var
h
Bitmap
Var
K-Spec
Length
3
1
Attribute
h
h
Key specifier for Issuer Master Key.
(Formats: 0 - 3, 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
IMKAC-Spec
PAN Data
AC/Shortened AC
Response Content
EF2011
rc
This function verifies an Application Cryptogram (TC, AAC, ARQC) that has been produced by an
ICC.
The ICC Master Key is used directly to calculate the Application Cryptogram, as specified by Visa in
reference [8].
FM
When Function Modifer = 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 13 accepted. Support provided for CBC only.
PAN Data
Formatted PAN and PAN Sequence No.
AC
Application Cryptogram (TC, AAC or ARQC) Calculated by ICC as defined
in Reference [1]. 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 [31].The Shortened AC field contains the bits of the
Application Cryptogram to be verfified 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.
© SafeNet, Inc.
221
ProtectHost White Mark II Programmer's 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 I 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].
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].
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.
PTK EFT 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
FM,
*IMK_AC,
PAN[8],
*AC,
*AC_DATA,
IN
222
KEYSPEC
*bitmap);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_GENERATE_ARPC
PHW
PSO
PTK EFT MK2
Card Issuance
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
Description
Function Code.
Function Modifier = 00
Var
K-Spec
8
16
1
1
2
8
Length
3
1
h
h
h
h
h
h
Attribute
h
h
Key specifier for Issuer Master Key.
(Formats: 0 - 3, 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
8
h
D
D
D
D
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 [5].
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 13 accepted. Support provided for CBC only.
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 I 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].
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].
3. Calculate the ARPC using SK and ARPC Data according to the method specified in 8.2 of
reference [5].
Note: ARPC Data should contain the value Y, which is the XORed combination of the ARQC
and the ARC.
© SafeNet, Inc.
223
ProtectHost White Mark II Programmer's 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.
PTK EFT 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
224
UCHAR
ARPC[8]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_SCRIPT_CRYPTO_EMV2000
D
D
D
D
PHW
PSO
PTK EFT MK2
Card Issuance
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
Response Content
EF2013
rc
Length
3
1
Attribute
h
h
eSKSMC(Text)
MAC
variable
8
h
h
SC
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, 13)
Key specifier for IMKSMC.
(Formats: 0 - 3, 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 [5].
FM
= 00. 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.
IMKSMI –Spec
Key specifier which provides access to the IMKSMI.
Formats 0 - 3, and 13 accepted. Support provided for CBC only.
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.
© SafeNet, Inc.
225
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
IMKSMC –Spec
Key specifier which provides access to the IMKSMC.
Formats 0 - 3, and 13 accepted. Support provided for CBC only.
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)
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 = 1 it is a standard Var field.
This function returns zero when completing successfully, otherwise an error is returned. Please refer
to Appendix I 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]
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].
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]
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].
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.
PTK EFT MK2
PTK EFT MK2 only supports the function when used with = 00 FM=01.
226
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
int EFT_EF2013_EMVScriptCrypto_EMV2000(
IN
UCHAR
IN
UCHAR
IN
KEYSPEC
IN
KEYSPEC
IN
UCHAR
IN
UCHAR
IN
UCHAR
IN
UCHAR
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],
IV[16],
H,
b,
ATC[2],
encrypt_mode,
*Text,
Offset,
*Script_Data,
*eSMC_Text,
MAC[8]);
227
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_SCRIPT_CRYPTO_VISA
PHW
PSO
PTK EFT MK2
Card Issuance
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
Response Content
EF2014
rc
Length
3
1
Attribute
h
h
eSKSMC(Text)
MAC
variable
8
h
h
SC
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, 13)
Key specifier for IMKSMC.
(Formats: 0 - 3, 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].
228
FM
= 00. 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 13 accepted. Support provided for CBC only.
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.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
IMKSMC –Spec
Key specifier which provides access to the IMKSMC.
Formats 0 - 3, and 13 accepted. Support provided for CBC only.
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)
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 I 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]. Derive the
ICC MAC Session Key (SKSMC) using the derived MKSMC and ATC, according to the method
specified in B.4 of reference [8].
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].
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.
PTK EFT MK2
PTK EFT MK2 only supports the function when used with = 00 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]);
229
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_PIN_CHANGE_UNBLOCK_VISA
PHW
PSO
PTK EFT MK2
Card Issuance
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
8
6
1
2
Var
Length
3
1
h
d
h
h
h
Attribute
h
h
Variable
8
h
h
P2
Validation Data
Offset
PIN Length
Script-Data Position
Script-Data
Response Content
EF2015
rc
New PIN Data
MAC
D
D
D
D
Description
Function Code
Function Modifier = 00
Function Flag
00 = PIN UnBlock only
01 = PIN Change/UnBlock using PIN
02 = PIN Change/UnBlock using PIN
Key specifier for IMKSMI, KMv31
(Formats: 0 - 3, 13)
Key specifier for IMKSMC, KMv32
(Formats: 0 - 3, 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, 13, 14)
Validation Data
Offset
PIN Length (Current PIN)
Script-Data Position
Script Data. Minimum length = 16 bytes
Description
Function Code
Return Code
Encrypted New PIN Data
Message Authentication Code
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.
230
FM
= 00. 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
IMKSMI –Spec
Issuer Master Key for secure message integrity key specifier.
Formats 0 - 3, and 13 accepted. Support provided for CBC only.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
IMKSMC –Spec
Issuer Master Key for secure message confidentiality key specifier.
Formats 0 - 3, and 13 accepted. Support provided for CBC only.
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 , 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.
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 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 Ref [9].
• 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”.
• Encrypt the delta PIN with the Data Encipherment SKs according to B.3 (figure B-2) of Ref
[9] to generate the encrypted new PIN data.
3. If the value of P2 is set to ‘02’ perform the following steps -
© SafeNet, Inc.
231
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
•
4.
5.
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 Ref [9].
• 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 Ref [9] to generate the encrypted new PIN data.
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 Ref [5]. Derive the ICC MAC Session Key (SKSMI)
using the derived MKSMI and ATC, according to the method specified in B.4 of Ref [9]
Calculate the MAC according to B.2 (figure B-1) of Ref [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.
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.
PTK EFT MK2
PTK EFT MK2 only supports the function when used with = 00 FM=01.
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
232
EFTBUFFER
UCHAR
FM,
P2,
*IMK_SMI,
*IMK_SMC,
PAN_data[8],
ATC[2],
*PPK,
ePPK_PIN[8],
ANB[6],
*PVK,
Validation_data[8],
Offset[6],
PIN_len,
Script_Data_Pos,
*Script_Data,
*New_PIN_Data,
MAC[8]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_PIN_CHANGE_UNBLOCK
D
U
D
D
PHW
PSO
PTK EFT MK2
Card Issuance
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, 13)
IMKSMC
Var
K-Spec
Key specifier for IMKSMC
(Formats 0 - 3, 13)
IMKAC
Var
K-Spec
Key specifier for IMKAC
(Formats 0 - 3, 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.
233
ProtectHost White Mark II Programmer's 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 2byte 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
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.
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.
PTK EFT 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
234
EFTBUFFER
UCHAR
*New_PIN_Data,
MAC[8]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_PIN_CHANGE_UNBLOCK_EMV_2000
D
U
D
D
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE2017
FM
Length
3
1
Attribute
h
h
P2
1
h
Scheme
1
h
IMKSMI
Var
K-Spec
Key specifier for IMKSMI
(Formats 0 - 3, 13)
IMKSMC
Var
K-Spec
Key specifier for IMKSMC
(Formats 0 - 3, 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.
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
235
ProtectHost White Mark II Programmer's 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.
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.
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.
PTK EFT 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,
IN
EFTBUFFER
*Script_Data,
OUT
OUT
236
EFTBUFFER
UCHAR
*New_PIN_Data,
MAC[8]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_VERIFY_AC_GEN_ARPC
D
D
D
D
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE2018
FM
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
238
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 239
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.
02 = Method 2.
Var
Length
3
1
Var
h
Attribute
h
h
h
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
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, 13)
Data on which the ARPC is calculated.
Description
Function Code
Return Code
4 or 8 byte ARPC.
Or zero-length field.
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.
© SafeNet, Inc.
237
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
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 240) 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 240 for a table of the common combinations of
methods.
The processing that the function must perform is specified in the Action
request field, as follows:
Action
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
Value 00
The following values of MK Method are supported:
Value
Implementation
Reference
00
Common
[1-8]
01
SECCOS
[9]
Field Content
PAN Data
Length
Attribute
6-16
h
Description
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
238
Length
Attribute
8-32
h
Description
Card Identification Number
The following values of AC Key Method are supported:
Value
Implementation
Reference
00
SKAC = MKAC
[7] VSDC 1.3.2
01
SKD function using ATC and
UN
[5], [9] M/Chip 2.1,
SECCOS
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
02
03
04
Value 00
Chapter 19
EMV Functions
Tree of keys using ATC, IV, H
and b
Treee of keys using ATC.
Fixed IV, H and b.
Xor using ATC
Field Content
Length
Null
Value 01
Value 02
Value 03
Field Content
© SafeNet, Inc.
Description
Length
Attribute
2
h
Applicatin Transaction
Counter
UN
4
h
Unpredicatable Number
Field Content
Description
Length
Attribute
ATC
2
h
Applicatin Transaction
Counter
IV
16
h
Initialization Vector
H
1
h
Height of tree of keys
b
1
h
Brance factor of tree of
keys
Length
Attribute
2
h
Length
Attribute
2
h
Field Content
Field Content
Description
Description
Applicatin Transaction
Counter
Description
Applicatin Transaction
Counter
The following values of AC Method are supported:
Value
ARPC Key Method
[1], [4] AEIPS, J/Smart
ATC
ATC
AC Method
[3] EMV 4.1 CCD
0
ATC
Value 04
Attribute
[2] EMV 4.0
ISO/IEC 9797-1 Alternatives
Reference
Algorithm
Pad Method
00
1
1
01
1
2
EMV
02
3
1
VSDC, AEIPS,
J/Smart
03
3
2
EMV, M/Chip,
SECCOS
The following values of ARPC Key Method are supported:
Value
Implementation
Reference
00
SKARPC = SKAC
All except M/Chip 2.1
01
SKARPC = MKAC
B
B
B
B
[5] M/Chip 2.1
239
ProtectHost White Mark II Programmer's Guide
01
Chapter 19
EMV Functions
SKARPC = MKAC
[5] M/Chip 2.1
The following values of ARPC Method are supported:
ARPC Method
Value 00
Value
Implementation
Reference
00
Method 1
All
01
Method 2
[3] EMV 4.1
Field Content
Length
Attribute
2
h
Length
Attribute
CSU
4
h
Applicatin Transaction
Counter
PAD
0-8
h
Proprietary Application
Data
ARC
Value 01
Field Content
Description
Authorization Response
Code
Description
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.
MK
AC Key
Methods
AC
ARPC Key
ARPC
AEIPS
00
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
Implementation
240
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
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
PTK EFT 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,
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
© SafeNet, Inc.
EFTBUFFER
*ARPC);
241
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
EMV_AC_GEN_MULTI
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE2019
FM
IMKAC
MK Method
MK Data
AC Key Method
AC Key Data
AC Method
AC Data
Response Content
EE2019
rc
AC
D
U
D
D
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
Key specifier for IMKAC
(Formats: 0 - 3, 13)
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
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 239
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.
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.
242
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
MK Method
Value 00
Chapter 19
EMV Functions
The following values of MK Method are supported:
Value
Implementation
Reference
00
Common
[1-8]
01
SECCOS
[9]
Field
Content
Length
Attribute
PAN Data
6-16
h
Description
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
Card Identification
Number
Reference
00
SKAC = MKAC
[7] VSDC 1.3.2
01
SKD function using ATC
and UN
Tree of keys using ATC, IV,
H and b
Treee of keys using ATC.
Fixed IV, H and b.
Xor using ATC
[5], [9] M/Chip 2.1,
SECCOS
[2] EMV 4.0
Field
Content
[1], [4] AEIPS, J/Smart
Description
Length
Attribute
Description
ATC
2
h
Applicatin Transaction
Counter
UN
4
h
Unpredicatable Number
Length
Attribute
2
h
Field
Content
Field
Content
ATC
Length
[3] EMV 4.1 CCD
Attribute
Null
© SafeNet, Inc.
h
Implementation
04
Value 02
8-32
Description
Value
03
Value 01
Attribute
The following values of AC Key Method are supported:
02
Value 00
Length
0
Description
Applicatin Transaction
Counter
243
ProtectHost White Mark II Programmer's Guide
Value 03
Chapter 19
EMV Functions
IV
16
h
Initialization Vector
H
1
h
Height of tree of keys
b
1
h
Brance factor of tree of
keys
Length
Attribute
2
h
Length
Attribute
2
h
Field
Content
ATC
Value 04
Field
Content
ATC
AC Method
Description
Applicatin Transaction
Counter
Description
Applicatin 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
EMV
02
3
1
VSDC, AEIPS,
J/Smart
03
3
2
EMV, M/Chip,
SECCOS
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
244
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
PTK EFT MK2
int
EFT_EE2019_ EMV_AC_Generate_MULTI (
IN
UCHAR
FM,
IN
KEYSPEC
*IMK_AC,
IN
UCHAR
MK_Method,
IN
EFTBUFFER
*MK_Data,
IN
UCHAR
AC_Key_Method,
IN
EFTBUFFER
*AC_Key_Data,
IN
UCHAR
AC_Method,
IN
EFTBUFFER
*AC_Data
_OUT UCHAR AC[8] );
© SafeNet, Inc.
245
ProtectHost White Mark II Programmer's Guide
Chapter 19
EMV Functions
THIS PAGE INTENTIONALLY LEFT BLANK
246
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
248
VCEPS_VER_SN
EF0702
250
VCEPS_GEN_SN
EF0703
252
VCEPS_MAC_VER_LSAM
EF0704
253
VCEPS_GEN_HASH_CEP
EF0F01
254
247
ProtectHost White Mark II Programmer's Guide
Chapter 20
CEPS Functions
VCEPS_VER_S1_GEN_S2
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EF0701
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
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
8
h
Response Content
EF0701
rc
S2
D
U
D
D
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 [12].
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 [12].
3. Calculate the S1 MAC using SK and the data provided in S1 Data, according to the method
specified in 5.1.3 of [12].
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 [12]. Return the result in S2.
Function usage
The function is used for Load / Unload and Currency Exchange authorization transactions.
248
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 20
CEPS Functions
PTK EFT 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]);
249
ProtectHost White Mark II Programmer's Guide
Chapter 20
CEPS Functions
VCEPS_VER_SN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EF0702
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
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
Response Content
EF0702
rc
D
U
D
D
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.
250
3.
Calculate the Sn MAC using SK and the data provided in Sn Data, according to the method
specified in 5.1.3 of [12].
4.
Compare the values of the calculated Sn and that supplied in Sn.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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].
PTK EFT 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.
251
ProtectHost White Mark II Programmer's Guide
Chapter 20
CEPS Functions
VCEPS_GEN_SN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EF0703
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
KMx-Spec
Var
K-Spec
Derivation Data
Var
h
Session Key Data
Var
h
Sn Data
Var
h
Length
3
1
Attribute
h
h
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
8
h
Response Content
EF0703
rc
Sn
D
U
D
D
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[12] Return the result in Sn.
Function usage
The function could be used generate any Sn MAC, e.g. for testing purposes.
PTK EFT MK2
int EFT_EF0703_VcepsGenSn(
IN
UCHAR
FM,
IN
KEYSPEC
*KMx,
IN
EFTBUFFER
*Deriv_Data,
IN
EFTBUFFER
*Session_Data,
IN
EFTBUFFER
*Sn_Data,
OUT
252
UCHAR
MAC_Sn[8]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 20
CEPS Functions
VCEPS_MAC_VER_LSAM
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EF0704
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
LSAMK-Spec
Var
K-Spec
eLSAMK(R1)
MACLSAM
Data
16
4
Var
h
h
h
Length
3
1
Attribute
h
h
Key specifier for LSAM
(Format: 11)
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
Response Content
EF0704
rc
D
U
D
D
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.
2.
3.
Recover the MAC key, R1
Calculate a MAC for Data, according to the method specified in 5.1.3 of [12].
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.
PTK EFT 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.
253
ProtectHost White Mark II Programmer's Guide
Chapter 20
CEPS Functions
VCEPS_GEN_HASH_CEP
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EF0F01
FM
KMx-Spec
IDCEP
Hash Data
Response Content
EF0F01
rc
HCEP
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
6
Var
Length
3
1
h
h
Attribute
h
h
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
10
h
D
U
D
D
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.
2.
3.
Derive the card's diversified key (KDL) using the Master Derivation Key and IDCEP, according
to the method specified in 3.5.1 of [12].
Calculate RCEP using KDL, according to the method specified in 3.6.1 of [12].
Note: The NETS document indicates that a OWF2(KDLcep. NTcep) is used to calculate RCEP.
This differs from the above.
Append RCEP to Hash Data, and use the resulting string to calculate HCEP according to the
method specified in 3.6.1 of [12].
PTK EFT MK2
int EFT_EF0F01_VcepsGenHashCep(
IN
UCHAR
FM,
IN
KEYSPEC
*KMx,
IN
UCHAR
IDcep[6],
IN
EFTBUFFER
*Hash_Data,
OUT
254
UCHAR
Hcep[10]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
256
KIS_SEND
EE3031
257
KIR_REC
EE3032
258
NODEPROOF
EE3033
259
NODERESP
EE3034
260
255
ProtectHost White Mark II Programmer's Guide
Chapter 21
AS2805.6.3 Support Functions
GETPUBLICKEY
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE3030
FM
PK-Spec
Response Content
EE3030
rc
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
Length
3
1
Attribute
h
x
Key specifier for HSM Public key pair.
(Formats: 0 - 3)
Description
Function Code
Return Code
1
x
20
Var
x
K-Spec
n
PVC(PKi HSM)
PKi HSM
D
U
D
D
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.
PTK EFT MK2
int EFT_EE3030_GetPublicKey(
IN
UCHAR
FM,
IN
KEYSPEC
*PK,
OUT
OUT
OUT
256
UCHAR
UCHAR
KEYSPEC
*ModLen,
PVC_PKI_HSM[20],
*PKI_HSM);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 21
AS2805.6.3 Support Functions
KIS_SEND
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE3031
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
SK-Spec
Var
K-Spec
PKr
Var
K-Spec
Length
3
1
Attribute
h
x
Key specifier for Index to SK HSM
(Formats: 0 - 3)
Receiver’s public Key
(Format: 80)
Description
Function Code
Return Code
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
D
U
D
U
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.
PTK EFT 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] );
257
ProtectHost White Mark II Programmer's Guide
Chapter 21
AS2805.6.3 Support Functions
KIR_REC
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE3032
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
SK-Spec
Var
K-Spec
sSKs HSM(hash of
key data)
ePKr HSM(KIR)
PKs-Spec
Var
S-Block
Key specifier for Index to SK HSM.
(Formats: 0 - 3)
Signed hash of KIR
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
U
D
U
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.
PTK EFT MK2
int EFT_EE3032_KirRec (
IN
UCHAR
FM,
IN
KEYSPEC
*SK,
IN
EFTBUFFER
*Signed_Hash,
IN
EFTBUFFER
*ePKr_KIR,
IN
KEYSPEC
*PK,
OUT
OUT
258
KEYSPEC
UCHAR
*KIR,
KVC_KIR [3] );
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 21
AS2805.6.3 Support Functions
NODEPROOF
PHW
PSO
PTK EFT MK2
Card Issuance
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
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.
PTK EFT MK2
int EFT_EE3033_NodeProof(
IN
UCHAR
FM,
IN
UCHAR
len,
IN
KEYSPEC
*KIS,
OUT
OUT
© SafeNet, Inc.
EFTBUFFER
EFTBUFFER
*eKISv82_RNs,
*eKISv84_RNr);
259
ProtectHost White Mark II Programmer's Guide
Chapter 21
AS2805.6.3 Support Functions
NODERESP
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE3034
FM
KIR-Spec
eKIRv82(RNs)
Response Content
EE3034
rc
eKIRv84(RNr)
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Var
K-Spec
Var
Length
3
1
h
Attribute
h
x
Key specifier for KIR
(Formats: 0 - 3, 15)
Encrypted Random Number
Description
Function Code
Return Code
Var
h
D
U
D
U
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.
PTK EFT MK2
260
int EFT_EE3034_NodeResp(
IN
UCHAR
IN
KEYSPEC
IN
EFTBUFFER
FM,
*KIR,
*eKIRv82_RNs,
OUT
*eKIRv84_RNr);
EFTBUFFER
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
262
261
ProtectHost White Mark II Programmer's Guide
Chapter 22
Key Block
GEN_TERMINAL_KEY
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0628
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
2
h
Exportability
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
00 = DPK
01 = PPK
02 = MPK
05 = KTM
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
262
D
U
D
U
Description
Function Code
Return Code
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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)
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.
The generated key may be provided in simple encrypted form or incorporated in a secure key Block.
See Appendix J References, references <25>, <26> and <27> for details on secure key Block formats.
FM
= 00. Must be set to zero.
KTM
The key specifier used to protect the key being generated.
Valid values are key specifier formats 0-3, 11 and 13 (DES 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:
Crypto algorithm
Key length
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 - DPK, PPK, MPK, KTM
Algorithm HMAC-SHA-1 - MPK
Terminal key
format
Identifies the format in which the key is to be transmitted to the terminal. Valid
formats are as follows:
‘01’ - ECB encrypted using a variant of KTM,
‘05’ - Verifone key Block (based on GISKE)
Host key format
Identifies the format in which the key is to be stored on the host. Formats are as
follows:
‘01’ - CBC encrypted using a variant of KM and supports 3DES key only. The
key is returned in a format 13 key specifier
‘02’ - binary key Block in a format 18 key specifier
KVC format
Key verification code standard format
Version identifier
‘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:
© SafeNet, Inc.
263
ProtectHost White Mark II Programmer's Guide
Exportability
Chapter 22
Key Block
Key type
Key usage
Mode of use
Key version
number
DPK
D0
D,E,N
00
MPK
M0
C,M,N,V
00
PPK
P0
N
00
KTM
K0
N
00
‘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.
PTK EFT 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,
264
_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);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
Chapter 23
ZKA Functions
Summary of ZKA Functions
Function Name
Function Code
Page
ZKA-IMPORT-MK
EE0210
269
ZKA-PIN-TRANS
EE0610
271
ZKA-PIN-VER
EE0611
273
ZKA-CALC-PVN
EE0612
275
ZKA-PIN-TRANS-1
EE0613
277
ZKA-MAC-GEN
EE0710
279
ZKA-MAC-GEN-1
EF0711
281
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
© SafeNet, Inc.
265
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
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 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
266
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
Field
PIN Length
Length
2 bits
4
Raw Value
10
Converted Value
Account Number
34 bits
8589939303
10 0000 0000 0000 0000 0001 0010 0110
0111
Card Sequence Number
4 bits
7
0111
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.
© SafeNet, Inc.
267
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
A key management function (ZKA-IMPORT-MK ) is provided though for the import of the ZKA
Master Key.
268
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
ZKA-IMPORT-MK
D
U
D
U
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0210
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
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
Var
K-Spec
Key specifier containing eKMx(K)
e*KTK(K)
*KTK-Spec
Response Content
EE0210
rc
K-Spec
This function translates an ECB- or CBC-encrypted MK to encryption by variant 18. of the Domain
Master Key for host storage. It optionally performs an integrity check on the clear MK using the
specified method. If the integrity check fails, a return code of 08 results (and the key is not reencrypted).
FM
= 00. Must be set to zero.
e*KTK(K)
Is the supplied key encrypted by a Key Transport Key (*KTK).
*KTK-spec
Supports only double-length ProtectHost White 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
Indicates the Key Type and KM variant used to encrypt for Host storage.
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.
© SafeNet, Inc.
269
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
PTK EFT 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]);
270
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
ZKA-PIN-TRANS
D
U
D
U
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0610
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
8
Var
x
K-Spec
PFi
1
h
ANB
PFo
6
1
h
h
Var
K-Spec
Length
3
1
Attribute
h
h
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, 09, 10, 11, 13)
Key Specifier for ZKA MK
(Format: 13)
Description
Function Code
Return Code
8
16
h
h
ePPKi(PIN)
PPKi-Spec
MK-Spec
Response Content
EE0610
rc
ePPKo(PIN)
RNDo
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 ProtectHost White 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,
ProtectHost White 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.
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).
© SafeNet, Inc.
271
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
PTK EFT 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
272
FM,
ePPKi_PIN[8],
*PPKi,
PFi,
ANB[6],
PFo,
*MK,
ePPKo_PIN[8],
RNDo[16]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
ZKA-PIN-VER
D
U
D
U
PHW
PSO
PTK EFT MK2
Card Issuance
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
Description
Function Code
Function Modifier = 00
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
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, 13, 91 )
10-digit Account Number
Card Sequence Number 00 - 09
Last digit only (00 – 09)
PIN Verification Number Type = 00 or 04
PIN Verification Number
Description
Function Code
Return Code
This function performs the verification of a PIN using the ecPVN method. The PIN is supplied in
encrypted form, using any of the PIN Block formats supported by the standard product (including
ISO formats 0 and 1).
FM
= 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 double-length,
ProtectHost White 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 ProtectHost
White Mark II-stored or double-length, ProtectHost White Mark II-stored or
double length host-stored 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.
PVN
Is the PIN Verification Number, used to verify the user’s PIN.
© SafeNet, Inc.
273
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
PTK EFT 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);
274
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
ZKA-CALC-PVN
PHW
PSO
PTK EFT MK2
Card Issuance
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
D
U
D
U
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
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, 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
Var
1
h
h
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 ProtectHost
White Mark II Programmers Guide.
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 double-length,
ProtectHost White 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 ProtectHost
White Mark II-stored or double-length, ProtectHost White Mark II-stored or
double length host-stored key.
Account No.
Is a 10 digit Account Number.
CSN
Is the Card Sequence Number.
Expiration Year
Is the last digit of the expiry year of the card.
© SafeNet, Inc.
275
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
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.
PTK EFT 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
276
*PVN,
*PIN_Length);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
ZKA-PIN-TRANS-1
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0613
FM
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
8
Var
x
K-Spec
PFi
1
h
ANB
PFo
6
1
h
h
Var
K-Spec
Length
3
1
Attribute
h
h
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
8
16
Var
h
h
K-Spec
ePPKi(PIN)
PPKi-Spec
MK2-Spec-1
Response Content
EE0613
rc
ePPKo(PIN)
RNDo
MK2-Spec-2
D
U
D
U
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 ProtectHost White 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
© SafeNet, Inc.
Account Number Block, which is the rightmost 12 digits of the Primary Account
Number (PAN), excluding the check digit.
277
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
PTK EFT 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
278
ePPKo_PIN[8],
RND[16],
*MK2_2);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
ZKA-MAC-GEN
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0710
FM
D
U
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: 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.
279
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
PTK EFT 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
280
EFTBUFFER
UCHAR
*MAC,
RND[16]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 23
ZKA Functions
ZKA-MAC-GEN-1
PHW
PSO
PTK EFT MK2
Card Issuance
Request Content
EE0711
FM
D
U
D
U
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
Alg
MAClen
ICD
MK2-Spec-1
1
1
8
Var
h
h
h
K-Spec
Data
Offset1
Offset2
Var
2
2
h
h
h
Offset3
2
h
Length
3
1
Attribute
h
h
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
Var
16
Var
h
h
K-Spec
Response Content
EE0711
rc
MAC
RND
MK2-Spec-2
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.)
281
ProtectHost White Mark II Programmer's Guide
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.)
Offset3
Note: ICD will normally be set equal to zero.
PTK EFT 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
282
*MAC,
RND[16],
*MK2_2);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 24
Administration Functions
Chapter 24
Administration Functions
GetKVC
PHW
PSO
PTK EFT
MK2
Request Content
EEBF29
FM
Key Type
Length
3
1
2
Attribute
h
x
h
D
D
D
Description
Function Code
Function Modifier = 00
00 = Get details on specified Key or
01 = Get details on next Key
Key Type (decimal)
01 - KIS
02 - KIR
03 - BDK
04 - PPK
05 - MPK
06 - DPK
07 - KTM
08 - PVK
09 - KM
10 - TRANSFER
11 - Key Being Loaded *
12 - KKL
13 - PVVK
14 - CVVK
15 - DPVT
16 - Current PINPAD *
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
© SafeNet, Inc.
283
ProtectHost White Mark II Programmer's Guide
Request Content
KVCType
Index
Response Content
EEBF29
rc
KeyLen
KeyType
KVC
Chapter 24
Administration Functions
Length
Attribute
2
h
2
Length
2
1
2
2
Var
h
Attribute
h
x
h
h
h
Description
36 - ZKA_KK
37 - ZKA_MK
38 - ZKA_KGK
39 - 3624_KTM
40 - 3624_BK
* - available on PSO only
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,
01 = Current KM,
02 = New KM
Description
Function Code
Return Code
Key Length of specified Key
8 – single length
16 – double length
24 – triple length
Key Table Type
If Transfer Table was specified then
this is the type of the key in the
Transfer Table
KVC of clear key (size depends on
KVC method)
This function allows an operator to verify the existance and obtain the KVC of keys stored in the
Secure Memory of the HSM device.
NOTES
KVC methods vary depending on the Key Type. PHW calculates KVCs with the same method the
console is using.
284
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 24
Administration Functions
PTK EFT 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);
285
ProtectHost White Mark II Programmer's Guide
Chapter 24
Administration Functions
THIS PAGE INTENTIONALLY LEFT BLANK
286
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 25
ABI Debit Card Functions
Chapter 25
ABI Debit Card Functions
PIN_Generation
PHW
PSO
PTK EFT
MK2
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
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)
PTK EFT 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]);
287
ProtectHost White Mark II Programmer's Guide
Chapter 25
ABI Debit Card Functions
Auth_Param_Generate
PHW
PSO
PTK EFT
MK2
Request Content
EF0617
FM
D
D
D
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
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
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.
PTK EFT 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
288
UCHAR
AP_value[8]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 25
ABI Debit Card Functions
Random_Key_Generation
PHW
PSO
PTK EFT
MK2
Request Content
EF0618
FM
KF
KMVar
Response Content
EF0618
rc
eKMvX(Key)
Length
3
1
Attribute
h
h
Description
Function Code
Function Modifier = 00
1
h
1
Length
3
1
h
Attribute
h
h
Key Format
(Formats: 10, 11, 13, 14)
KM Variant Index
Description
Function Code
Return Code
Var
K-Spec
D
D
D
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.
PTK EFT 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);
289
ProtectHost White Mark II Programmer's Guide
Chapter 25
ABI Debit Card Functions
THIS PAGE INTENTIONALLY LEFT BLANK
290
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
Chapter 26
Superceded Functions
IT-PPK-GEN
PHW
PSO
PTK
EFT
MK2
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
eKTMn(PPK)
eKMv1(PPK)
D
U
U
PIN Protect Key
PIN Protect Key
This function generates a random initial PIN Protect Key (PPK) for an EFT terminal.
For transmitting to the EFT terminal, the key is returned encrypted under the Terminal Master Key
(KTMn) indicated by the specified index (KTM Index). It is also returned encrypted under the Master
Key Variant 1(KMv1) for storage within the host.
NOTE
•
•
© SafeNet, Inc.
This function is superseded by function EE0400
This function only supports use of the first 99 KTMs.
291
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
IT-MPK-GEN
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0400.
292
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
IT-DPK-GEN
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0400.
© SafeNet, Inc.
293
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
NT-PPK-GEN
PHW
PSO
PTK
EFT
MK2
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
8
8
B64
B64
PIN Protect Key
PIN Protect Key
ePPKn(PPKn+1)
eKMv1(PPKn+1)
D
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 superseded by function EE0401.
294
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
NT-MPK-GEN
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0401.
© SafeNet, Inc.
295
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
NT-DPK-GEN
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0401.
296
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
GEN_SESS_KEYS
PHW
PSO
PTK
EFT
MK2
Request Content
4A
KTM-Spec
Key Flags
Response Content
4A
rc
1
eKTM(KS)
eKMx(KS)
1
1
Length
1
Attribute
h
Description
Function Code
Var
K-Spec
2
Length
1
1
h
Attribute
h
h
Key specifier for KTM
(Formats: 0 - 3)
Key Type generation specifier.
Description
Function Code
Return Code
8
8
B64
B64
D
U
U
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 superseded by function EE0400.
© SafeNet, Inc.
297
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
TERM-VER
PHW
PSO
PTK
EFT
MK2
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
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
•
298
This function is superseded by function EE0406.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
II-PPK-GEN
PHW
PSO
PTK
EFT
MK2
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
eKISnv1(PPK)
eKMv1(PPK)
D
U
U
PIN Protect Key
PIN Protect Key
This function generates a random initial interchange PIN Protect Key (PPK).
For transmitting to the receiving institution, the key is returned encrypted under variant 1 of the
Interchange Sending Key (KISn) indicated by the specified index (KIS Index). It is also returned
encrypted under KM variant 1, for storage within the host.
eKISnv1(PPK)
is the session key encrypted under variant 1 of KISn. The variant is determined
by the variant scheme associated with KISn.
KIS range = 01 - 99.
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 superseded by function EE0402.
299
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
II-MPK-GEN
PHW
PSO
PTK
EFT
MK2
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
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
•
•
300
This function will check the length of KISn and use the appropriate encryption method.
This function is superseded by function EE0402.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
II-DPK-GEN
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0402.
301
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
II-PPK-RCV
PHW
PSO
PTK
EFT
MK2
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
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 reencrypts 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
•
•
302
This function will check the length of KIRn and use the appropriate encryption method.
This function is superseded by function EE0403.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
II-MPK-RCV
PHW
PSO
PTK
EFT
MK2
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
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 re-encrypts 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 superseded by function EE0403.
© SafeNet, Inc.
303
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
II-DPK-RCV
PHW
PSO
PTK
EFT
MK2
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
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 re-encrypts 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
•
•
•
•
304
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 superseded by function EE0403.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
NI-PPK-GEN
PHW
PSO
PTK
EFT
MK2
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
8
8
B64
B64
PIN Protect Key
PIN Protect Key
ePPKn(PPKn+1)
eKMv1(PPKn+1)
D
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 superseded by function EE0404.
305
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
NI-MPK-GEN
PHW
PSO
PTK
EFT
MK2
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
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
•
306
This function is superseded by function EE0404.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
NI-DPK-GEN
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0404.
307
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
NI-PPK-RCV
PHW
PSO
PTK
EFT
MK2
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
8
B64
PIN Protect Key
eKMv1(PPKn+1)
D
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
•
308
This function is superseded by function EE0405.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
NI-MPK-RCV
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0405.
309
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
NI-DPK-RCV
PHW
PSO
PTK
EFT
MK2
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
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
•
310
This function is superseded by function EE0405.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PIN-TRAN
PHW
PSO
PTK
EFT
MK2
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
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.
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.
NOTE
•
© SafeNet, Inc.
This function is superseded by function EE0602.
311
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PIN-VER-IBM-ANSI
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
312
This function is superseded by function EE0603.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PIN-VER-PP
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
© SafeNet, Inc.
This function is superseded by function EE0603.
313
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
D51-PIN-TRAN
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
314
This function is superseded by function EE0602.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
D51-PIN-VER
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
© SafeNet, Inc.
This function is superseded by function EE0603.
315
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
VAR-PIN-VER
PHW
PSO
PTK
EFT
MK2
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
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.
See Appendix A IBM 3624 PIN Verification Method for a more detailed overview of the PIN
verification procedure.
NOTE
•
316
This function is superseded by function EE0603.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
VAR-PIN-VER-PP
PHW
PSO
PTK
EFT
MK2
Request Content
68
Length
1
Attribute
h
PVK-Index
ePPK(PP-PIN)
1
8
d
B64
8
8
1
6
Length
1
1
B64
h
h
h
Attribute
h
h
eKMv1(PPK)
PAN
CHKLEN
Offset
Response Content
68
rc
D
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.
See Appendix A IBM 3624 PIN Verification Methodfor a more detailed overview of the PIN
verification procedure.
NOTE
•
© SafeNet, Inc.
This function is superseded by function EE0603.
317
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PIN-OFF-AS
PHW
PSO
PTK
EFT
MK2
Request Content
6A
Length
1
Attribute
h
Description
Function Code
PVK-Index
ePPK(AS-PIN)
eKMv1(PPK)
PAN
ANB
Response Content
6A
rc
1
8
8
8
6
Length
1
1
d
B64
B64
h
h
Attribute
h
h
Index of PVK
AS/ANSI formatted PIN Block
Encrypted PPK
Primary Account Number
Account Number Block
Description
Function Code
Return Code
6
1
h
h
Offset
PINLEN
D
U
U
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.
NOTE
•
318
This function is superseded by function EE0604.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PIN-OFF-PP
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
© SafeNet, Inc.
This function is superseded by function EE0604.
319
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
MAC-GEN
PHW
PSO
PTK
EFT
MK2
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
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
•
320
This function is superseded by function EE0701.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
MAC-TRAN
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0701.
321
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
MAC-VER
PHW
PSO
PTK
EFT
MK2
Request Content
72
Length
1
Attribute
h
Blocks
eKMv2(MPKi)
Data
MAC
1
8
bks*8
4
h
B64
h
h
Response Content
72
rc
Length
1
1
Attribute
h
h
D
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
•
322
This function is superseded by function EE0701.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
ENCIPHER
PHW
PSO
PTK
EFT
MK2
Request Content
80
Length
1
Attribute
h
Description
Function Code
Blocks
eKM(DPK)
Data
Response Content
80
rc
1
8
bks*8
Length
1
1
h
B64
h
Attribute
h
h
No of 8 byte Blocks
Encrypted DPK
Must be multiple of 8 bytes
Description
Function Code
Return Code
eDPK(Data)
bks*8
B64
Data encrypted under DPK
D
U
U
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 superseded by function EE0800.
323
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
DECIPHER
PHW
PSO
PTK
EFT
MK2
Request Content
81
Length
1
Attribute
h
Description
Function Code
Blocks
eKM(DPK)
eDPK(Data)
Response Content
81
rc
1
8
bks*8
Length
1
1
h
B64
B64
Attribute
h
h
No of 8 byte Blocks
Data Protect Key
Must be multiple of 8 bytes
Description
Function Code
Return Code
Data
bks*8
h
D
U
U
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
•
324
This function is superseded by function EE0801.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
ENCIPHER-ECB
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0800.
325
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
DECIPHER-ECB
PHW
PSO
PTK
EFT
MK2
Request Content
83
Length
1
Attribute
h
Description
Function Code
Blocks
eKM(DPK)
eDPK(Data)
Response Content
83
rc
1
8
bks*8
Length
1
1
h
B64
B64
Attribute
h
h
No of 8 byte Blocks
Data Protect Key
Must be multiple of 8 bytes
Description
Function Code
Return Code
Data
bks*8
h
D
U
U
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
•
326
This function is superseded by function EE0801.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PVV-GEN-1
PHW
PSO
PTK
EFT
MK2
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
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 ProtectHost White 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 superseded by function EE0606.
327
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PVV-VER-1
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
328
This function is superseded by function EE0605.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PVV-VER-2
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
© SafeNet, Inc.
This function is superseded by function EE0605.
329
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PVV-VER-3
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
330
This function is superseded by function EE0605.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PIN-TRAN-1
PHW
PSO
PTK
EFT
MK2
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
U
U
Encrypted PIN
This function performs a PIN Translation from the local Key (PPK) to the Visa Acquirer Key
(AWK).
NOTE
•
© SafeNet, Inc.
This function is superseded by function EE0602.
331
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PIN-TRAN-2
PHW
PSO
PTK
EFT
MK2
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
U
U
This function performs a PIN Translation from a Visa Issuer Key (IWK) to the local Key (PPK).
NOTE
•
332
This function is superseded by function EE0602.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PVV-GEN-2
PHW
PSO
PTK
EFT
MK2
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
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 superseded by function EE0606.
333
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PVV-VER-4
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
334
This function is superseded by function EE0605.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PVV-VER-5
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
© SafeNet, Inc.
This function is superseded by function EE0605.
335
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PVV-VER-6
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
336
This function is superseded by function EE0605.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
PVV-CHANGE
D
U
PHW
PSO
PTK
EFT
MK2
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
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.
NOTE
•
© SafeNet, Inc.
This function is superseded by function EE0607.
337
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
CVV-GEN
PHW
PSO
PTK
EFT
MK2
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
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 ProtectHost White stored CVKA/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
•
338
This function is superseded by function EE0802.
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
CVV-VER
PHW
PSO
PTK
EFT
MK2
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
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 ProtectHost White stored CVKA/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 superseded by function EE0803.
339
ProtectHost White Mark II Programmer's Guide
Chapter 26
Superceded Functions
THIS PAGE INTENTIONALLY LEFT BLANK
340
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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.
© SafeNet, Inc.
341
ProtectHost White Mark II Programmer's Guide
Appendix A
IBM 3624 PIN Verification Method
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.
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
342
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix A
IBM 3624 PIN Verification Method
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.
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
© SafeNet, Inc.
343
ProtectHost White Mark II Programmer's Guide
Appendix A
IBM 3624 PIN Verification Method
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.
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
344
© SafeNet, Inc.
ProtectHost White Mark II Programmer's 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
345
ProtectHost White Mark II Programmer's Guide
Appendix B
EFT Terminal Functions
THIS PAGE INTENTIONALLY LEFT BLANK
346
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix C
PIN Management Function Examples
Appendix C
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
347
ProtectHost White Mark II Programmer's Guide
Appendix C
PIN Management Function Examples
THIS PAGE INTENTIONALLY LEFT BLANK
348
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix D
EMV Function Examples
Appendix D
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
349
ProtectHost White Mark II Programmer's Guide
Appendix D
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
Transmitted to HSM
Function code
= 00
00
(Var) IDN-index
Application PAN Block
Random Number
Returned from HSM
Function code
Return code
ICC Dynamic Number
IDN (2 bytes)
350
EE 20 04
02 00 22
01 23 45 67 89 01 23 45
EF 5E EF F8 2C E6 76 A8
EE 20 04
00
BA 33
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix D
EMV Function Examples
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
351
ProtectHost White Mark II Programmer's Guide
Appendix D
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 CryptogramEMV2000(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)
352
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
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix D
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
Returned From HSM
Function code
Return code
ARPC
EF 20 12
00
50 7F CF 54 BB 34 1D FB
© SafeNet, Inc.
20 12
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
353
ProtectHost White Mark II Programmer's Guide
Appendix D
EMV Function Examples
EMV function EF2013 - Script Crypto- EMV2000
Transmitted To HSM
Function code
= 00
Select Code (SC)
(Var) SMI spec
(Var) SMC spec
Application PAN Block
Initialization Vector
Height
Branch factor
ATC
Encryption Mode
Var) Text-Data
Text-Data
Offset
(Var) Script Data
Data
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
354
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
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix E
American Express Account Blocks
Appendix E
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.
355
ProtectHost White Mark II Programmer's Guide
Appendix E
American Express Account Blocks
THIS PAGE INTENTIONALLY LEFT BLANK
356
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix F
American Express Examples
Appendix F
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 Eracom 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
357
ProtectHost White Mark II Programmer's Guide
Appendix F
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
358
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
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix F
American Express Examples
Test 7
Transmitted to HSM:
SOM
LENGTH
Application Data
BCC
EOM
Received From HSM:
SOM
LENGTH
Application Data
BCC
EOM
3C
0C
A8 02 00 01 99 12 00 10 80 88 90 12
7A
3E
3C
08
A8 00 77 02 86 18 45 55
7D
3E
Test 8
Transmitted to HSM:
SOM
LENGTH
Application Data
BCC
EOM
Received From HSM:
SOM
LENGTH
Application Data
BCC
EOM
© 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
359
ProtectHost White Mark II Programmer's Guide
Appendix F
American Express Examples
THIS PAGE INTENTIONALLY LEFT BLANK
360
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix G
Function Matrix
Appendix G
Function Matrix
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 ProtectHost White Mark II release. The
column headed PSO, lists the functions that are available in the ProtectServer Orange Mark II
release. The column headed PTK EFT MK2, details the functions included in the PTK EFT MK2
API. The column headed PHW CI lists the functions documented in this Guide that are also in the
ProtectHost White 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
supersede one or more functions. These relationships are detailed in the Supersedes and Superseded
by columns.
Func.
Code
© SafeNet, Inc.
Function Name
PHW
PSO
PTK EFT
MK2
PHW
CI
Supersede
s
Supersede
d 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
361
ProtectHost White Mark II Programmer's Guide
Func.
Code
362
Function Name
Appendix G
Function Matrix
PHW
PSO
PTK EFT
MK2
PHW
CI
Supersede
s
Supersede
d by
5C
NI-DPK-RCV
EE0405
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.
ProtectHost White Mark II Programmer's 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
EE0002
GEN_RANDOM
EE0200
KEY_IMPORT
Appendix G
Function Matrix
PHW
PSO
PTK EFT
MK2
PHW
CI
Supersede
s
EE0201
KEY_EXPORT
EE0202
GET_KEY_DETAILS
EE0210
ZKA-IMPORT-MK
EE0400
IT_KEY_GEN
41,42,43,4A
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
EE0628
GEN_TERMINAL_KEY
EE0640
Generate KM-encrypted PIN
EE0641
Print a KM-encrypted PIN
EE0642
Verify a PIN Using KM-encrypted PIN
EE0643
Translate a PIN from PPK to LMK
EE0644
Migrate PIN
© SafeNet, Inc.
Supersede
d by
90,96
9A
363
ProtectHost White Mark II Programmer's Guide
Func.
Code
364
Function Name
Appendix G
Function Matrix
PHW
PSO
PTK EFT
MK2
PHW
CI
Supersede
s
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_EMV_
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
EE9008
Generate SHA Hash
EE9101
Generate Key – Diebold
Supersede
d by
70,71,72
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Func.
Code
Function Name
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_VISA
© SafeNet, Inc.
Appendix G
Function Matrix
PHW
PSO
PTK EFT
MK2
PHW
CI
Supersede
s
Supersede
d by
365
ProtectHost White Mark II Programmer's Guide
Appendix G
Function Matrix
THIS PAGE INTENTIONALLY LEFT BLANK
366
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
Appendix H
PTK EFT MK2
This appendix provides information on the use of the PTK EFT 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:
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)
typedef struct {
UCHAR
// Represents Key Spec 15
© SafeNet, Inc.
version;
367
ProtectHost White Mark II Programmer's Guide
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
} FORMAT15;
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];
Appendix H
PTK EFT MK2
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
UCHAR
} FORMAT80;
368
// Represents Key Spec 80
modulusLen;
modulus[512];
exponentLen;
exponent[512];
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
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];
Appendix H
PTK EFT MK2
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 {
// Represents Key Spec 91
UCHAR format_KGK1;
union {
FORMAT00
KGK1_fmt00;
FORMAT01
KGK1_fmt01;
FORMAT02
KGK1_fmt02;
© SafeNet, Inc.
369
ProtectHost White Mark II Programmer's Guide
FORMAT03
FORMAT13
Appendix H
PTK EFT MK2
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;
370
// Universal Key Spec
// One of.....
fmt00;
fmt01;
fmt02;
fmt03;
fmt10;
fmt11;
fmt13;
fmt15;
fmt16;
fmt50;
fmt51;
fmt80;
fmt81;
fmt82;
fmt90;
fmt91;
fmt92;
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
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 maximium 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 unfifned.
© SafeNet, Inc.
371
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
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.
PTK EFT 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
*RAMStatus,
UCHAR
*ROMStatus,
UCHAR
*DESStatus,
UCHAR
*HostPortStatus,
UCHAR
*BatteryStatus,
UCHAR
*HardDiskStatus,
UCHAR
*RSAAccelerator,
UCHAR
*PerformanceLevel,
USHORT
*ResetCount,
ULONG
*CallsInLastMinute,
ULONG
*CallsInLast10Minutes,
EFTBUFFER *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
_OUT
372
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
*Num_Files,
LogFileStatus[31],
LogFileStatus1[31],
LogFileStatus2[31],
LogFileStatus3[31],
LogFileStatus4[31],
LogFileStatus5[31],
LogFileStatus6[31],
LogFileStatus7[31],
LogFileStatus8[31],
LogFileStatus9[31],
LogFileStatus10[31]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
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(
IN
UCHAR
variantNum,
© SafeNet, Inc.
373
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
IN
UCHAR
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,
OUT
374
EFTBUFFER
*eKISvK,
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
OUT
UCHAR
Appendix H
PTK EFT MK2
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,
_IN
UCHAR
*LineNo1b,
375
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
_IN
_IN
UCHAR
EFTBUFFER
*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,
OUT
KEYSPEC
*eKMv5_KTM);
extern "C" EXPORT int EFT_EE0400_InitialSessionKeyGeneration(
IN
UCHAR
FM,
IN
KEYSPEC
*KTM,
IN
UCHAR
KeyFlags[2],
376
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],
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
_OUT
_OUT
_OUT
EFTBUFFER
KEYSPEC
UCHAR
Appendix H
PTK EFT MK2
*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,
OUT
KEYSPEC
*PKo);
extern "C" EXPORT int EFT_EE9004_ImportPublicKeyCertificate(
IN
UCHAR
FM,
© SafeNet, Inc.
377
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
IN
IN
IN
IN
IN
IN
KEYSPEC
UCHAR
UCHAR
EFTBUFFER
UCHAR
EFTBUFFER
*PK_CA,
CertFormat,
HashFunction,
*Certificate,
KeyType[2],
*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,
IN
UCHAR
KeyType,
OUT
OUT
OUT
378
EFTBUFFER
EFTBUFFER
KEYSPEC
*KT_B1,
*r_HOST,
*K_KTM);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
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,
© SafeNet, Inc.
OUT
UCHAR
*numKeys,
OUT
OUT
KEYSPEC
UCHAR
*KS1,
KVC1[3],
_OUT
_OUT
KEYSPEC
UCHAR
*KS2,
KVC2[3],
379
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
_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,
380
_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]);
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
PIN Mangement 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);
VISA Functions
extern "C" EXPORT int EFT_EE0605_PINVerify_VISA(
IN
UCHAR FM,
IN
UCHAR ePPKi_PIN[8],
IN
KEYSPEC
*PPKi,
© SafeNet, Inc.
381
ProtectHost White Mark II Programmer's Guide
IN
IN
IN
IN
IN
Appendix H
PTK EFT MK2
UCHAR PFi,
UCHAR ANB[6],
KEYSPEC
*PVVK,
UCHAR TSP12[6],
UCHAR PVV[2]);
extern "C" EXPORT int EFT_EE0606_CalculatePVV_IBM(
IN
UCHAR FM,
IN
KEYSPEC
*PVK,
IN
UCHAR PAN[8],
IN
UCHAR Offset[2],
IN
KEYSPEC
*PVVK,
IN
UCHAR TSP12[6],
OUT
UCHAR PVV[2]);
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,
382
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
OUT
UCHAR
Appendix H
PTK EFT MK2
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],
IN
KEYSPEC
*MPK,
IN
EFTBUFFER
*mac,
IN
EFTBUFFER
*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
© SafeNet, Inc.
EFTBUFFER
*OCV,
383
ProtectHost White Mark II Programmer's Guide
OUT
EFTBUFFER
Appendix H
PTK EFT MK2
*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,
OUT
OUT
OUT
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
384
UCHAR
CSC[6] );
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
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,
IN
KEYSPEC
*KIR,
IN
UCHAR
eKIR_CSCK[16],
OUT
OUT
KEYSPEC
UCHAR
*CSCK,
KVC[3]);
PIN Issuance Functions
extern "C" EXPORT int EFT_E2_PinMailer(
IN
UCHAR
*ESMID,
IN
UCHAR
PVKIndex,
IN
UCHAR
PAN[8],
IN
UCHAR
PinLen,
IN
UCHAR
PinType,
© 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
UCHAR
UCHAR
*LineNo8,
*ColumnNo8,
385
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
_IN
EFTBUFFER
*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,
IN
UCHAR
PFo,
IN
UCHAR
ANB[6],
IN
KEYSPEC
*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],
386
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,
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
_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
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,
© SafeNet, Inc.
387
ProtectHost White Mark II Programmer's Guide
IN
IN
IN
IN
KEYSPEC
UCHAR
UCHAR
UCHAR
Appendix H
PTK EFT MK2
*IMK_IDN,
APANB[8],
RN[8],
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,
IN
UCHAR
SC,
IN
KEYSPEC
*IMK_SMI,
IN
KEYSPEC
*IMK_SMC,
IN
UCHAR
APANB[8],
IN
UCHAR
RN[8],
IN
EFTBUFFER
*Text,
IN
USHORT
Offset,
IN
EFTBUFFER
*Script_Data,
OUT
OUT
EFTBUFFER
UCHAR
*eSMC_Text,
MAC[8]);
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,
388
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
IN
IN
IN
IN
IN
KEYSPEC
UCHAR
EFTBUFFER
EFTBUFFER
KEYSPEC
Appendix H
PTK EFT MK2
*IMK_AC,
PAN[8],
*AC,
*AC_DATA,
bitmap);
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]);
389
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
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]);
CEPS Functions
extern "C" EXPORT int EFT_EF0701_VcepsVerS1GenS2(
IN
UCHAR
FM,
IN
KEYSPEC
*KMx,
IN
UCHAR
IDcep[6],
IN
UCHAR
NTcep[2],
IN
UCHAR
MAC_S1[8],
IN
EFTBUFFER
*S1_Data,
IN
EFTBUFFER
*S2_Data,
OUT
UCHAR
MAC_S2[8]);
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);
390
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
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(
IN
UCHAR
FM,
IN
KEYSPEC
*SK,
IN
EFTBUFFER
*Signed_Hash,
IN
EFTBUFFER
*ePKr_KIR,
IN
KEYSPEC
*PK,
OUT
OUT
KEYSPEC
UCHAR
*KIR,
KVC_KIR[3]);
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,
© SafeNet, Inc.
391
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
IN
IN
IN
IN
IN
IN
IN
IN
IN
IN
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
UCHAR
TerminalKeyFormat,
HostKeyFormat,
KVCFormat,
VerID,
KeyUsage[2],
Mode,
KeyVerNum[2],
Export,
Padding,
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
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,
392
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
IN
IN
IN
UCHAR
UCHAR
UCHAR
Appendix H
PTK EFT MK2
Expiration_Year,
PVN_Type,
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,
OUT
OUT
OUT
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
© SafeNet, Inc.
EFTBUFFER
UCHAR
KEYSPEC
*MAC,
RND[16],
*MK2_2);
393
ProtectHost White Mark II Programmer's Guide
Appendix H
PTK EFT MK2
THIS PAGE INTENTIONALLY LEFT BLANK
394
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix I
Error Codes
Appendix I
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 ProtectHost White was tampered or all Keys deleted
Uninitiated key accessed. Key or decimalization table (DT) is not stored in the ProtectHost White.
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.
Zero PIN length.
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
Invalid key specifier length
Unsupported key specifier
Invalid key specifier content
Invalid key specifier format
Invalid = 00
Invalid key attributes
Hash process failed
Invalid Key Type - Not Triple DES
Unsupported Triple Des Index
Invalid administrator signature
No administration session
Invalid file type
Invalid signature
KKL disabled
No PIN pad
Pin pad timeout
08
09
0A
0B
0C
0F
0F
10
11
12
13
14
15
16
17
19
20
21
22
23
24
25
27
28
29
30
32
33
34
35
36
37
© SafeNet, Inc.
395
ProtectHost White Mark II Programmer's Guide
Error
Code
Meaning
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
7F
80
81
82
83
90
F0
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
Invalid Print Token
OAEP Decode Error
OAEP Invalid Header Byte
OAEP Invalid PIN Block
OAEP Invalid Random Number
General Printer Error
Zero length PIN
396
Appendix I
Error Codes
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix J
References
Appendix J
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]
[32]
[33]
[34]
[35]
© 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.
Common Personalization Specification,Visa International, Version 1.5, January 2002.
Global Platform Card Specification, Global Platform, Version 2.1, June 2001.
Schnittstellen Spezifikation für die ZKA-Chipkarte: Secure Chip Card Operating System
(SECCOS), Version 5.0, June 2001.
EMV Integrated Circuit Card Specification for Payment Systems: Book 2 – Security and Key
Management, Version 4.1, May 2004.
397
ProtectHost White Mark II Programmer's Guide
Appendix J
References
THIS PAGE INTENTIONALLY LEFT BLANK
398
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix K
Glossary
Appendix K
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
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).
© SafeNet, Inc.
399
ProtectHost White Mark II Programmer's Guide
Appendix K
Glossary
KI-index
Refer to XX-index.
KK
ecPIN Verification Key
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.
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.
400
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix K
Glossary
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.
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 e-commerce, 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.
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
ProtectHost White.
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.
401
ProtectHost White Mark II Programmer's Guide
Appendix K
Glossary
THIS PAGE INTENTIONALLY LEFT BLANK
402
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Appendix L
Function List
Appendix L
Function List
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 LMK................................
Migrate PIN....................................................................
IT-PVK-EXPORT..........................................................
OBM GetPublicKey() ....................................................
OBM GenerateRandomNumber.....................................
© SafeNet, Inc.
Page
E3 ........................................22
01.........................................26
FFF0 ....................................28
FFF1 ....................................30
11.........................................34
12.........................................35
13.........................................37
21.........................................40
22.........................................41
EE0200 ................................42
EE0201 ................................44
EE0202 ................................46
EE3100 ................................48
EE3101 ................................50
EE0E01................................54
EE0400 ................................58
EE0401 ................................61
47.........................................63
49.........................................64
EE0406 ................................65
EE0408 ................................66
EE9001 ................................70
EE9003 ................................72
EE9004 ................................73
EE9005 ................................75
EE9006 ................................76
EE9007 ................................77
EE9008 ................................78
EE9101 ................................79
EE9102 ................................80
EE9201 ................................81
EE0402 ................................84
EE0403 ................................88
EE0404 ................................91
EE0405 ................................93
EE0600 ................................97
EE0601 ................................98
EE0602 ................................100
EE0603 ................................102
63.........................................104
64.........................................105
69.........................................106
EE0604 ................................107
EE0609 ................................109
EE0640 ................................111
EE0641 ................................112
EE0642 ................................114
EE0643 ................................115
EE0644 ................................116
EF0210 ................................117
EE3000 ................................123
EE3001 ................................124
403
ProtectHost White Mark II Programmer's Guide
Function
Appendix L
Function List
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...................
404
Page
EE3002 ............................... 125
EE3003 ............................... 126
EE3004 ............................... 128
EE3005 ............................... 129
EE3006 ............................... 130
EE3008 ............................... 131
EE3009 ............................... 133
EE3016 ............................... 134
EE3017 ............................... 135
EE3018 ............................... 136
EE3019 ............................... 138
EE3020 ............................... 139
EE0605 ............................... 147
EE0606 ............................... 149
EE0607 ............................... 150
EE0614 ............................... 152
EE0616 ............................... 154
EE0615 ............................... 156
EE0802 ............................... 158
EE0803 ............................... 159
EE0700 ............................... 162
EE0701 ............................... 164
EE0702 ............................... 166
73 ........................................ 168
EE0800 ............................... 170
EE0801 ............................... 172
EE0804 ............................... 174
EE0805 ............................... 176
EE0806 ............................... 178
84 ........................................ 180
85 ........................................ 181
A0 ....................................... 185
A1 ....................................... 186
A2 ....................................... 187
A3 ....................................... 188
A7 ....................................... 189
A8 ....................................... 193
A9 ....................................... 194
AA ...................................... 195
AB ...................................... 196
E2........................................ 200
EE0E04............................... 202
EE0E05............................... 203
EE0002 ............................... 206
EE2000 ............................... 207
EE2001 ............................... 208
EE2002 ............................... 211
EE2003 ............................... 212
EE2004 ............................... 213
EE2005 ............................... 214
EE2006 ............................... 215
EE2007 ............................... 216
EF2010 ............................... 218
EF2011 ............................... 221
EF2012 ............................... 223
EF2013 ............................... 225
EF2014 ............................... 228
EF2015 ............................... 230
© SafeNet, Inc.
ProtectHost White Mark II Programmer's Guide
Function
Appendix L
Function List
Function Code
Page
EMV_PIN_CHANGE_UNBLOCK...............................
EMV_PIN_CHANGE_UNBLOCK_EMV_2000..........
EMV_VERIFY_AC_GEN_ARPC ................................
EMV_AC_GEN_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 ........................................................
EE2016 ................................233
EE2017 ................................235
EE2018 ................................237
EE2019 ................................242
EF0701 ................................248
EF0702 ................................250
EF0703 ................................252
EF0704 ................................253
EF0F01 ................................254
EE3030 ................................256
EE3031 ................................257
EE3032 ................................258
EE3033 ................................259
EE3034 ................................260
EE0628 ................................262
EE0210 ................................269
EE0610 ................................271
EE0611 ................................273
EE0612 ................................275
EE0613 ................................277
EE0710 ................................279
EE0711 ................................281
Error! Cannot open file referenced on page
283
Error! Cannot open file
referenced on page 283
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 .....................................................................
EEBF29 ...............................283
EF0616 ................................287
EF0617 ................................288
EF0618 ................................289
41.........................................291
42.........................................292
43.........................................293
44.........................................294
45.........................................295
46.........................................296
4A........................................297
4C ........................................298
51.........................................299
52.........................................300
53.........................................301
54.........................................302
55.........................................303
56.........................................304
57.........................................305
58.........................................306
59.........................................307
5A........................................308
5B ........................................309
5C ........................................310
60.........................................311
61.........................................312
62.........................................313
65.........................................314
66.........................................315
67.........................................316
68.........................................317
6A........................................318
6B ........................................319
70.........................................320
© SafeNet, Inc.
405
ProtectHost White Mark II Programmer's Guide
Function
Appendix L
Function List
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 .....................................................................
Page
71 ........................................ 321
72 ........................................ 322
80 ........................................ 323
81 ........................................ 324
82 ........................................ 325
83 ........................................ 326
90 ........................................ 327
91 ........................................ 328
92 ........................................ 329
93 ........................................ 330
94 ........................................ 331
95 ........................................ 332
96 ........................................ 333
97 ........................................ 334
98 ........................................ 335
99 ........................................ 336
9A ....................................... 337
9B ....................................... 338
9C ....................................... 339
END OF DOCUMENT
406
© SafeNet, Inc.