safenet programmers guid

7/29/2019 Safenet Programmers Guid

1/522


2/522

Mark IIProgrammers Guide Copyright

Copyright

All intellectual property is protected by copyright. All trademarks and product names used or referred toare the copyright of their respective owners. No part of this document may be reproduced, stored in aretrieval 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 andspecifically 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 timein the content hereof without the obligation upon SafeNet to notify any person or organization of any suchrevisions or changes.

SafeNet invites constructive comments on the contents of this document. These comments, together withyour personal and/or company details, should be sent to the address below.

SafeNet, Inc.4690 Millennium DriveBelcamp, Maryland 21017USA

Copyright 2009, SafeNet, Inc.

All rights reserved.

We have attempted to make this document complete, accurate, and useful, but we cannot guarantee it tobe perfect. When we discover errors or omissions, or they are brought to our attention, we endeavor tocorrect them in succeeding releases of the product. SafeNet, Inc. is not responsible for any direct or indirectdamages or loss of business resulting from inaccuracies or omissions. The specifications contained in thisdocument are subject to change without notice.

SafeNet HSM Payment (SHP) is a trademark of SafeNet, Inc. All other product names referenced herein aretrademarks or registered trademarks of their respective manufacturers.

Part Number 003198-002, Revision TSoftware versions 1.1

Revision Action/Change DateO This revision was skipped for Document

Control reasons.

June 2009

P SHP 1.1 Release. MarkII Programmers Guide

updated for:

June 2009

1.Card Issuance Integration2.Host Key rationalization

3.Network Key Transfer Host Functions

Q This revision was skipped for Document

Control reasons.

October 2009

R Functionality enhanced for FM=2 in

function EE2048 and EE2058.

October 2009

S This revision was skipped for Document

Control reasons.

December 2009

T Updated for a few host functions December 2009

SafeNet, Inc. i


3/522

Mark IIProgrammers Guide Copyright

Certifications

FCC Compliance

SafeNet HSM Payment device has been tested and found to comply with the limits for a Class B digitaldevice, pursuant to part 15 of the FCC Rules.

FCC Notice to Users

These limits are designed to provide reasonable protection against harmful interference in a residential installation.This equipment generates, uses and can radiate radio frequency energy and if not installed and used in accordancewith the instructions, may cause harmful interference to radio communications. However, there is no guaranteethat interference will not occur in a particular installation. If this equipment does cause harmful interference toradio or television reception, which can be determined by turning the equipment off and on, the user is encouraged

to try to correct the interference by one or more of the following measures:

Reorient or relocate the receiving antenna. Increase the separation between the equipment and receiver. Connect the equipment into an outlet on a circuit different from that to which the receiver is connected. Consult the dealer or an experienced radio/TV technician for help.

To ensure FCC compliance only devices also known to comply should be connected to the SHP (Ethernet Connect).If such devices do not feature their own cables, shielded cables must be used.

WEEE and RoHS Compliance

SafeNet HSM Payment devices comply with Waste Electrical andElectronic Equipment (WEEE) and Restriction of Hazardous Substances(RoHS) standards. When discarding, these devices must be handed overto a designated collection point for the recycling of waste electrical andelectronic equipment

SafeNet, Inc. ii


4/522

Mark IIProgrammers Guide Table of Contents

Table of Contents

Copyright.............................................................................................................................................................. iCertifications ............................................................................................................................................................. ii

FCC Compliance...................................................................................................................................................... iiFCC Notice to Users ................................................................................................................................................iiWEEE and RoHS Compliance ..................................................................................................................................ii

Table of Contents ..............................................................................................................................................iii

Preface............................................................................................................................................................... viiWhere to Find Information ?...................................................................................................................................viiContacting Technical Support ................................................................................................................................vii

Part 1 ................................................................................................................................................................... 1

Chapter 1 Introduction ..................................................................................................................................... 3Overview ...................................................................................................................................................................3

Product Architecture......................................................................................................................................... 4Design Paradigm.......................................................................................................................................................4

Implementation.........................................................................................................................................................4Using the ProtectToolkit EFT APIs ..........................................................................................................................4

Common Terms and Phraseology.............................................................................................................................4Encryption Notation..................................................................................................................................................4Supplemental Documentation ..................................................................................................................................5Host Function Overview ...........................................................................................................................................5

Chapter 2 Function Construction .................................................................................................................... 7Host Function Overview ...........................................................................................................................................7Function Message Formats .......................................................................................................................................7

Data Item Representation in Request/Response Messages .........................................................................................7Common Message Header Formats ..........................................................................................................................8Transmission of Two-byte Integers...........................................................................................................................8

Function Modifier Values..........................................................................................................................................8Variable Length Fields in Function Request and Response Messages ......................................................................9Example Field Formats......................................................................................................................................... 11

Variants.................................................................................................................................................................. 13KM Variants........................................................................................................................................................ 13SafeNet Variant Scheme ....................................................................................................................................... 13Atalla Variant Scheme.......................................................................................................................................... 14AS2805.6.1 Variant Scheme ............................................................................................................................... 14

Public Key Verification Code.................................................................................................................................. 15The Key Specifier Function Field.......................................................................................................................... 15

Key Specifier Formats for HSM-stored Keys.......................................................................................................... 16Key Specifier Formats for Host-stored Keys........................................................................................................... 17Usage Notes for Key Specifiers In Host Functions .................................................................................................. 24PIN Block Formats............................................................................................................................................... 25

Function Identifier Control .................................................................................................................................... 26Message Meta-function Format ............................................................................................................................. 26

Chapter 3 The Metafunction...........................................................................................................................27Message Meta-function Format ............................................................................................................................. 27

Chapter 4 HSM Status Functions ...................................................................................................................31The Error Log ......................................................................................................................................................... 31

Chapter 5 KM Change Functions ...................................................................................................................39

Chapter 6 Transfer Functions.........................................................................................................................45

Chapter 7 HSM Software UpgradeFunctions ...............................................................................................55Chapter 8 EFT Terminal Functions................................................................................................................61

Initial Session Key Generation ............................................................................................................................... 66

Rollover Session Key Generation ........................................................................................................................... 69Docutel Key Generation ......................................................................................................................................... 71

SafeNet, Inc. iii


5/522


3624 Comms Key Generation................................................................................................................................ 72Terminal Verification............................................................................................................................................. 73DUKPT BDK Generation......................................................................................................................................... 74

Chapter 9 Remote ATM Initialization Functions..........................................................................................77Overview ................................................................................................................................................................ 77

Key Types ............................................................................................................................................................... 78Authentication of public keys ................................................................................................................................ 78Storage of RSA keys ............................................................................................................................................... 78

Chapter 10 Interchange Functions................................................................................................................93Initial Session Key Generation ............................................................................................................................... 94Receive Initial Session Key..................................................................................................................................... 97Rollover Session Key Generation ......................................................................................................................... 101Receive Rollover Session Key ............................................................................................................................... 103

Chapter 11 PIN Management Functions .....................................................................................................105Host Stored PVK Management ............................................................................................................................ 105PIN Encryption..................................................................................................................................................... 107PIN Translation.................................................................................................................................................... 110PIN Verification.................................................................................................................................................... 112PINKEY PIN Translation...................................................................................................................................... 114Base Key PIN Verification .................................................................................................................................... 115Base Key PIN Verification - Variable Length ....................................................................................................... 116PIN Offset Generation........................................................................................................................................... 117

Chapter 12 Online Banking Module Functions..........................................................................................129

Summary of Online Banking Module Functions.............................................................................................. 129Online Banking Module Password Restrictions................................................................................................... 129Function Field Constructs .................................................................................................................................... 130

Data Item Representation in Request/Response Messages .................................................................................... 130EPB Processing Unit .......................................................................................................................................... 130CTPV Processing Unit ........................................................................................................................................ 131

Chapter 13 Visa Functions............................................................................................................................151

Visa Overview ...................................................................................................................................................... 151Key Management Operations .............................................................................................................................. 153Visa Function Overview....................................................................................................................................... 155Visa 3DES Support ............................................................................................................................................... 156Diebold Table Support .......................................................................................................................................... 163SEED Translation ................................................................................................................................................. 167

Chapter 14 MAC Management Functions ...................................................................................................171MAC Generation .................................................................................................................................................. 172Terminal Master Key MAC Generation................................................................................................................ 178

Chapter 15 Data Ciphering Functions.........................................................................................................1793624 B-Key Enciphering...................................................................................................................................... 1903624 B-Key Deciphering...................................................................................................................................... 191

Chapter 16 MasterCard Functions...............................................................................................................193MasterCard Security Requirements ..................................................................................................................... 193Facilities for MasterCard Support......................................................................................................................... 193MasterCard 3DES Support.................................................................................................................................... 194

Chapter 17 American Express Functions ....................................................................................................201Card Security Code Keys (CSCK) .......................................................................................................................... 201

Chapter 18 PIN Issuance Functions.............................................................................................................207PIN Issuance Overview ........................................................................................................................................ 207Separating PIN Generation and Printing............................................................................................................. 207

Chapter 19 EMV Functions ...........................................................................................................................215

Chapter 20 CEPS Functions ..........................................................................................................................267

Chapter 21 AS2805.6.3 Support Functions................................................................................................275

Chapter 22 Key Block....................................................................................................................................281

Chapter 23 ZKA Functions............................................................................................................................285

SafeNet, Inc. iv


6/522


Session Key Derivation......................................................................................................................................... 285Pin Verification .................................................................................................................................................... 285

Message Authentication Functions...................................................................................................................... 287Key Management Functions ............................................................................................................................... 287

Chapter 24 Administration Functions ........................................................................................................303

Chapter 25 ABI Debit Card Functions.........................................................................................................305Chapter 26 Superceded Functions...............................................................................................................309

Chapter 27 MasterCard PayPass and Visa payWave..................................................................................359MasterCard PayPass............................................................................................................................................. 359Visa payWave....................................................................................................................................................... 359

Chapter 28 Network Key Transfer...............................................................................................................365Network Key Transfer .......................................................................................................................................... 365

New Key ............................................................................................................................................................ 365

Part 2 ...............................................................................................................................................................369

Chapter 29 Card Issuer Key Management and Operational Requirements............................................371Overview .............................................................................................................................................................. 371ICC Initialization .................................................................................................................................................. 371

Issuer Key Pair Initialization .............................................................................................................................. 371Static Data Authentication.................................................................................................................................. 371Dynamic Data Authentication............................................................................................................................. 371Offline PIN Encipherment................................................................................................................................... 372Reference PIN Management................................................................................................................................ 372

Key Management ................................................................................................................................................. 372Function Construction ......................................................................................................................................... 373

Chapter 30 PIN Management Functions.....................................................................................................375Host Stored PVK Management ............................................................................................................................ 375

Chapter 31 Card Issuer Functions ...............................................................................................................379Key Types ............................................................................................................................................................. 379Issuer Key Management ...................................................................................................................................... 380

ICC Key Management .......................................................................................................................................... 396Dynamic Data Authentication............................................................................................................................. 410PIN Encipherment................................................................................................................................................ 412PIN Initialization.................................................................................................................................................. 414

Chapter 32 MasterCard PayPass and Visa payWave..................................................................................423Visa payWave:...................................................................................................................................................... 423MasterCard PayPass:............................................................................................................................................ 423

Part 3 ...............................................................................................................................................................429

Appendix A IBM 3624 PIN Verification Method.........................................................................................431Definitions ............................................................................................................................................................ 431Verification of a Derived PIN................................................................................................................................ 431Verification of a Random PIN .............................................................................................................................. 432

Selecting Significant Offset Digits......................................................................................................................... 433Appendix B EFT Terminal Functions ...........................................................................................................435

Appendix C Card Issuance Function Examples...........................................................................................437

Appendix D PIN Management Function Examples.....................................................................................439

Appendix E EMV Function Examples............................................................................................................441

Appendix F American Express Account Blocks ..........................................................................................447How To Form An Account Block ......................................................................................................................... 44734 Cards ............................................................................................................................................................... 447

Appendix G American Express Examples.....................................................................................................449Test Program Output ........................................................................................................................................... 449

Appendix H Function Matrix - MarkII .........................................................................................................453

Appendix I SHP Toolkit..................................................................................................................................459SHP Toolkit MK2.................................................................................................................................................. 459

SafeNet, Inc. v


7/522


Structures Representing Individual Key Specifiers................................................................................................ 459Structure Representing All Key Specifiers............................................................................................................ 462Structure Representing Variable Length Character Arrays. .................................................................................. 463API Helper Functions ......................................................................................................................................... 463Error Translation Functions ............................................................................................................................... 464Optional IO Fields in Functions........................................................................................................................... 464SHP Toolkit MK2 Functions............................................................................................................................... 464

SHP Toolkit CI ...................................................................................................................................................... 494

Appendix J Error Codes..................................................................................................................................501

Appendix K References MarkII and CI......................................................................................................503MarkII References ................................................................................................................................................ 503Card Issuance References..................................................................................................................................... 504

Appendix L Glossary.......................................................................................................................................507

Appendix M Function List MarkII and Card Issuance.............................................................................511

SafeNet, Inc. vi


8/522

Mark IIProgrammers Guide Preface

SafeNet, Inc. vii

PrefaceThis document, together with the ProtectHost White Card Issuance and the Mark II function sets, describes thecryptographic and key management functionality of the functions in support of card issuers.

This Guide covers standard Mark II and Card Issuance functionality. It provides a complete function reference forall functions that make up the Mark II and Card issuance function set.

Where to Find Information ?

Information Recommended ReferencesMarkII Function Set Information Chapter 1 -27, under Part 1 of the Guide

Card Issuance Function Set

Information

Chapters under Part 2 of the Guide

Appendices Appendicesunder Part 3 of the Guide

Appendix A - IBM 3624 PIN Verification Method Appendix B - EFT Terminal Functions Appendix C - Card Issuance Function Examples Appendix D - PIN Management Function Examples Appendix E - EMV Function Examples Appendix F - American Express Account Blocks Appendix G - American Express Examples Appendix H - Function Matrix (MarkII) Appendix I - SHP Toolkit Appendix J - Error Codes Appendix K - References Appendix L - Glossary Appendix M - Function list

Contacting Technical Support

If you encounter a problem while installing, registering or operating this product, please make sure that youhave 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 forfurther information about your entitlements, including the hours when telephone support is available to you.Technical Support Contact Information:Phone: 800-545-6608Email: [email protected]
mailto:[email protected]:[email protected]:[email protected]


9/522

Mark IIProgrammers Guide Preface

SafeNet, Inc. viii


10/522

Mark IIProgrammers Guide

Part 1

______________________________________________________________________

MarkII Function Set

SafeNet, Inc. 1


11/522

Mark IIProgrammers Guide

SafeNet, Inc. 2


12/522

Mark IIProgrammers Guide Chapter 1Introduction

SafeNet, Inc. 3

Chapter 1Introduction

OverviewThis Guide covers standard Mark II and Card Issuance functionality. It provides a completefunction reference for all functions that make up the Mark II and Card issuance function set.These function sets, which are supported on SafeNet Hardware Security Modules (HSMs), may beutilized by EFT network designers to implement a variety of key and PIN management schemes.

Mark II and Card Issuance functions are available as standard on the following SafeNet HSMproducts. These are the;

ProtectHost EFT (referred to as SHP, hereafter)

ProtectHost White Mark II

ProtectHost White Card Issuance

ProtectServer Orange

The Mark II and Card Issuance function set is not implemented in its entirety on each of theseHSM products. Rather, a unique subset of functions is provided to suit HSM design andapplication requirements in each case.

Additionally, further functions may also be available.

SafeNet also develops custom functions to meet the specific needs of particular customers.Details can be found in a customization guide supplied with the product, where applicable.

The SHP product provides an application programming interface in the C programminglanguage. SHP Toolkit MK2, is a component within this product, that allow third parties to easilyinterface to the SHP, HSM and ProtectServer Orange security modules running the MarkII andCard Issuance software. The SHP Toolkit MK2 is also described in this Guide.


13/522


Product Architecture

Design ParadigmThe paradigm used for the design of the MarkII/ Card Issuance hardware security module (HSM)is of an issuer computer with connected card personalization system. Sensitive values generatedby the HSM (card keys and PINs) are passed to the host in encrypted form using a transport key.The sensitive values are then passed to the card personalization system.

Implementation

Using the ProtectToolkit EFT APIs

It is possible to simplify system implementation by making use of the SafeNet productProtectToolkit EFT. ProtectToolkit EFT offers host applications all of the available functions on the

ProtectHost White Card Issuer HSM, in C callable form. The ProtectToolkit EFT product is madeup of two application programming interfaces (APIs), SHP Toolkit CI and SHP Toolkit MK2. Thisis shown in the diagram below.

SHP Toolkit MK2 implements C calls for those functions that are available on the Mark II, aswell as the Card Issuer HSM.

SHP Toolkit CI implements C calls for those functions that are available on the Card IssuerHSM alone.

The C call function prototypes for each of the available functions can be found at the end of theirfunction descriptions, in this guide. The sections are labelled with the applicable ProtectToolkitEFT name: SHP Toolkit CI and SHP Toolkit MK2 in this guide.

Common Terms and PhraseologyThis or other documentation may refer to a SafeNet HSM security module as an ESM, ESM2000,and HSM/PHeft. The device has been renamed as SafeNet HSM Payment (referred to as SHP,hereafter). The names SafeNet HSM Payment (SHP), PHeft, ESM, HSM and ESM2000 all refer tothe same device in the context of this or previous Guides. The Glossary at the back of this Guideexplains some of the many terms, abbreviations and acronyms used in this guide.

Encryption NotationThe notation used for encryption and decryption is as follows:

eK(D) where data D is encrypted under the key K.

dK(D) where data D is decrypted with the key K.

SafeNet, Inc. 4


14/522


Supplemental DocumentationThe Programmers Guide is supplemental to the following documentation:For SafeNet HSM Payment (SHP) MarkII and Card Issuance users:

MarkII Communications Guide

MarkII Installation Guide - SHP

MarkII Console User Guide

HSM Software Loader Help

For Customizations:

For customizations, specific information may be available in the form of a customization guide.

Host Function OverviewEach function involves a host request being sent to the HSM. Each request produces acorresponding response message containing the results of the function or a status code indicatingan error. The message content of each function is described in this guide and is independent of theselected communications protocol. Message formatting procedures appropriate to each availableprotocol 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 requiringvariable length data include the length of the variable field in a one-byte length parameter. Wherea function requires multiple fields in a message, there is no delimiter between fields.

For example Function NT-PPK-GEN (FN 44) :

eKM1(KSn) = 12 34 56 78 90 AB CD EF

By adding the function code the complete host request message is

44 12 34 56 78 90 AB CD EF

A response message starts with the Function Code from the host request message followed by aone-byte Return Code. Appendix I Error Codes lists the assignments for the Return (Error) Code. Ifthe Error Code returned is non-zero, there is no data following the Error Code. Otherwise, theresponse 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 thespecification takes the following format.

The function name appears at the left side of the page. It is important to note that this is anabbreviated form of the function name that is used in the Console. For a list of Host Functioncodes and associated function names, refer to the section entitled Appendix H Function Matrix.

To the right of the function name, a table lists the products in which the function is supported.SHP refers to the SafeNet HSM Payment product running the Mark II software.PSO/PHWrefersto the ProtectServer Orange/HSM product running the Mark II software. SHP Toolkit MK2 refers

to the ProtectTookit EFT MK2 application programming interface (API). Card Issuance refers to the

SafeNet, Inc. 5


15/522


HSM product running the Card Issuance software. AD indicates that the function is supported inthe product. AU indicates that it is not supported in the product.The specification of the function follows the title. For those functions that are supported in theSHP Toolkit MK2, the function definition is provided following the specification, as illustratedbelow.

Figure 1 Function definition format

SafeNet, Inc. 6


16/522

Mark IIProgrammers Guide Chapter 2Function Construction

SafeNet, Inc. 7

Chapter 2Function Construction

Host Function OverviewEach function involves a host request being sent to the HSM. Each request produces acorresponding response message containing the results of the function or a status code indicatingan error. The message content of each function is described in this guide and is independent of theselected communications protocol. Message formatting procedures appropriate to each availableprotocol 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 requiringvariable length data include the length of the variable field in a one-byte length parameter. Where

a function requires multiple fields in a message, there is no delimiter between fields.

For example Function NT-PPK-GEN (FN 44):

eKM1(KSn) = 12 34 56 78 90 AB CD EF

By adding the function code the complete host request message is

44 12 34 56 78 90 AB CD EF

A response message starts with the Function Code from the host request message followed by aone-byte Return Code. Appendix J Error Codes lists the assignments for the Return (Error) Code. Ifthe Error Code returned is non-zero, there is no data following the Error Code. Otherwise, theresponse 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 Decrypt in Electronic Code Book (ECB) mode.e Encrypt in Electronic Code Book (ECB) mode.

Qualifier Meaning

L The left part of a key pairR The right part of a key pairr Used for receivings Used for sending

V Variant


17/522


Each field has an associated attribute and its length in bytes. The attributes are defined as follows:

Attribute Description

b Represents a binary digit. These are always in multiples of 8.h Represents a hexadecimal digit. These are always grouped in pairs.

d Represents a BCD digit. These are always in pairs.x Represents a binary byte.B64 Represents a 64 bit field.B512 Represents a 512 bit field.P-key Represents an RSA public key.K-Spec Key specifier. A value that specifies the length, format and index for

a key.S-Block Represents a variable length, DEA 2 enciphered data Block

Common Message Header Formats

All functions employ a common format for both request and response messages.

Function Request HeadersEach 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 HeadersEach 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 fieldshould be transmitted with the most significant byte first unless otherwise stated.

Function Modifier ValuesSelection of host key protection method within host functions can be done using the FM field. TheHost Key Protection using Function Modifier can be in the range of x0, where x= 0 , 1 or 2.

This impacts the key-types under the Response Content since they are generated based on thechosen operation on console and FM. The following table shows different combinations of FMvalue and console check box and their impact on behavior of the host function.

Notes:FM override is only applicable for those functions that return key specifier in response. For thefunctions that receive key spec in request, FM (xy) and x>0 will cause an error.

Also, Functions not having FM fields will generate keys according to global method.

SafeNet, Inc. 8


18/522


State of FMOverride onconsole

Global MethodSelected

FM xy Key Protection Method to be used

Enabled Legacy 0000 0000 Legacy method

Legacy 0001 0000 ECB methodLegacy 0010 0000 CBC methodECB 0000 0000 ECB methodECB 0001 0000 ECB methodECB 0010 0000 CBC methodCBC 0000 0000 CBC methodCBC 0001 0000 ECB methodCBC 0010 0000 CBC method

Disabled Legacy 0000 0000 Legacy methodLegacy 0001 0000 Error (conflict with global method).

Error code : 0x24 FN_INVALID_FN_MODIFIERLegacy 0010 0000 Error (conflict with global method).

Error code : : 0x24 FN_INVALID_FN_MODIFIERECB 0000 0000 ECB methodECB 0001 0000 ECB (No conflict with global method)ECB 0010 0000 Error (conflict with global method).

Error code : : 0x24 FN_INVALID_FN_MODIFIERCBC 0000 0000 CBC methodCBC 0001 0000 Error (conflict with global method).

Error code : : 0x24 FN_INVALID_FN_MODIFIER

CBC 0010 0000 CBC (No conflict with global method)

Variable Length Fields in Function Request and ResponseMessages

This section describes the method for specifying the actual length of a variable-length data field ina function request or response. The method utilizes a length prefix that in itself has a variablelength. The length prefix forms an essential part of the variable-length data field. Host functionsutilize two field constructs, namely the Variable-length fieldand the Key specifier.

The variable-length field construct provides a standard mechanism for incorporating a field ofvarying length into HSM Request or Response messages. It comprises the variable-length dataand a prefix which specifies the length of the data, and which is also of variable-length. Thissection describes the method for specifying the actual length of a variable-length data field in afunction request or response. The actual length of the length prefix is specified by the mostsignificant bits of the most significant byte within the prefix. The remaining bits within the mostsignificant byte form part (or all, in the single-byte case) of the value of the length prefix. Thus:

Length of length prefix Length indicator bits in most significant byte

(bytes)

1 02 103 110 4 1110

The encoding defined above results in the following ranges of values for the length prefixes, andranges of lengths for the corresponding data values:

Length of Values in length

length prefix prefix Bytes in data value(bytes) (hex) (hex) (dec)

SafeNet, Inc. 9


19/522


SafeNet, Inc. 10

1 00 7F 00 7F 0 1272 8000

BFFF

0000 3FFF 0 16383

3 C00000 DFFFFF 000000 1FFFFF 0 2097151

4 E0000000 EFFFFFFF 00000000 0FFFFFFF 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 functionrequest or request message, with an indicated length of Var. Therefore, there is no need toindicate the length as a separate field.

The length prefix indicates the length of the data portion of the field, i.e. the length prefix isnot 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. bigendian. This is in line with the general rule for all multi-byte integer fields in Mark IIfunctions.

The method as defined above is open-ended, and therefore could be extended to a lengthprefix of more than four bytes. However, the HSM supports a maximum of four bytes for alength prefix.

For variable-length fields in response messages, the length prefix consists of the minimumnumber 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 prefixcontaining the value zero, e.g. X00 or X8000. A zero-length field is useful where a field isnot optional, but is not used.


20/522

Mark II Programmers Guide

Example Field Formats

The following examples illustrate how a variable-length field containing 27 data bytes could be represented using a length prefix o

One byte length

msb b1s

SafeNet Technologies

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 b b1sb ms 1s

1 0 b13 b12 b11 b10 b09 b08 b07 b06 b05 b04 b03 b02 b01 b00

1 0 indicates two byte length field

Length is 14 bit binary number (b13b12...b01b00)

Three byte length

First byte transmitted Second byte transmitted Third byte transmitted

msb b b b b1sb ms 1s ms 1s1 1 0 b20 b19 b18 b17 b16 b15 b14 b13 b12 b11 b10 b09 b08 b07 b06 b05 b04 b03 b02 b01 b00

1 1 0 indicates three byte length field

Length is 21 bit binary number (b20b19b01b00)


21/522

SafeNet Technologies

Mark II Programmers Guide

Four byte length

First byte transmitted Second byte transmitted Third byte transmitted Fourth b

msb b b b b b b1s ms 1s ms 1s ms 1 1 1 0 b27 b26 b25 b24 b23 b22 b21 b20 b19 b18 b17 b16 b15 b14 b13 b12 b11 b10 b09 b08 b07 b06

indicates four byte length field - Length is 28 bit binary number (b27b26...b01b00)1 1 1 0


22/522


Variants

KM Variants

The following KM variants are used to encrypt host stored keys.

Variant Value Used to encrypt:0 X00 DPK1 X28 PPK2 X24 MPK3 X44 KIS4 X88 KIR5 X22 KTM6 X20 CSCK7 X18 KPV, DT8 X14 KPVV

9 X48 KCVV10 X45 Key Block encryption - terminal11 X4D Key Block message authentication terminal14 X5C KTPV16 X0C KGK17 X0A KKBLZ18 X1E MK-ZKA19 X2E MAC used for Format 15 host stored keys20 X4E (K) used for Format 15 host stored keys24 X72 BDK25 X78 Key Block encryption host26 X70 Key Block message authentication host

27 X74 PIN Block encryption KM encrypted PIN30 X30 IMK-AC31 X36 IMK-SMI32 X3A IMK-SMC33 X3C IMK-DAC34 X50 IMK-IDN35 X66 KTK36 X6A PTK37 X6C KMC38 X7E IMK-CVC

The variant constant is obtained by repeating the variant byte from the above table 16 times.

SafeNet Variant Scheme

Variants of KIS/KIR keys are used to provide functional separation as described in AS2805 Part6.1, 1988. The variant is calculated as described in AS2805 Part 6.1, 1988 using the constantsdefined in the tables below.

The variant constant is formed by repeating the Variant Byte from the following table 8 times (forsingle length keys) or 16 times (for double length keys).

Note that no variant is applied to KIS/KIR keys used to encrypt DPK keys. Support for KTM keysadded in SafeNet Variant Scheme.

SafeNet, Inc. 13


23/522


Variant Byte Used to Protect

X'24' MPK

X'28' PPK

X'22' KTM

Atalla Variant Scheme

The Atalla key management system separates DPK, PPK and MPK keys by storing anddownloading then under different variants of KIS/KIR keys.

Single length key variants are formed by exclusive oring (XOR) the variant byte with the left mostbyte of the key. Double length key variants are formed by exclusive oring (XOR) the variant bytewith 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 Byte

variant

Used to Protect

1 X'08' PPK

2 X'10' DPK

3 X'18' MPK

AS2805.6.1 Variant Scheme

Variants of KIS/KIR keys are used to provide functional separation as described in AS2805 Part

6.1, 2002. The variant is calculated as described in AS2805 Part 6.1, 2002 using the constantsdefined 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 thestandard has been extended as described below. In each case the variant key is obtained by anXOR operation of the base key with the Variant Constant.

Variant Used to Protect

Byte

DPKX'22'

X'24' MPK

PPKX'28'

Size of Session Key Method

The variant constant is obtained by repeating the VariantByte from the above table to yield an 8 byte constant.

64-bit DEA keys

The variant constant is obtained by concatenating thevariant byte from the above table with the constant xC0 andrepeating these 2 bytes 8 times to yield a 16 byte constant.

128 bit CBC and DEA keys

The variant constant is obtained by concatenating the

variant byte from the above table with the constant x30 andrepeating these 2 bytes 12 times to yield a 24 byte constant.

192 bit CBC and DEA keys '

SafeNet, Inc. 14


24/522


Public Key Verification CodeThe KVC for a public key (PVC) is formed as described in AS2805 part 6.1 as follows:

The modulus and public exponent are each expressed as whole bytes, most significant bytefirst, with no length field and no leading zero bytes.

The modulus and exponent are concatenated in that order. The SHA1 digest of that data is calculated.

The first 64 bits of the SHA1 digest will be the PVC of the key.

The Key Specifier Function FieldHost functions utilize two field constructs, namely the Variable-length fieldand the Key specifier.

The key specifier construct is a variable-length field that contains a variable-format specificationof a key. In general, a key specifier may contain either an index to an HSM-stored key, or anencrypted 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 andprivate keys are also covered.

Most host functions perform transformations using cryptographic keys which are stored eitherwithin 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 per-key-type basis and has been fixed in the function design. The key specifier introduces thecapability for that choice to be at the discretion of the user (or host software provider); it alsopermits the possibility to HSM-store some keys of a key type and to host-store other keys of thatsame key type.

To support the capability, a key specifier is defined which is a variable format field to be built intohost 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 keytable).

Being variable format, a key specifier field will be variable length. Refer to the section entitledVariable Length Fields in Function Request and Response Messages for details of the variablelength field.

Although the key specifier introduces extra flexibility for the user, there need be no extracomplexity for the host programmer. One simply selects the appropriate key specifier format forthe particular key, and then treats that instance of the key specifier as a fixed length, fixed formatfield.

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 includesformats which support two-byte packed BCD indices, and one- and two-byte binary indices,thereby significantly increasing the maximum index supported. The following formats aredefined.

SafeNet, Inc. 15


25/522


Key Specifier Formats for HSM-stored Keys

The following key specifier formats provide access to keys stored in tables (or files) within HSMSecure Memory. The formats incorporate an index which identifies the required key in a table; theparticular 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 SecureMemory. All tables are indexed from one, so zero is an invalid value.

Index - short / BCD

Format 00 byte attribute content

Field length: 2 1 x 00

2 d 00 - 99

Index - short / binary



2 x 00 - FF

Index - long / BCD



2-3 d 0000 - 9999

Index - long / binary



2-3 x 0000 - FFFF

SafeNet, Inc. 16


26/522


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

The field lengths shown for formats 10-14 below assume DES keys appropriate to currentfunctionalities. However, the algorithm and associated key length is not implicit in the keyspecifier; so these formats could be equally appropriate for other algorithms, and might then havea different field length.

Encrypted key - Single-length



2-9 x eKMx(K)

Encrypted key - Double-length - ECB


Field length: 17 1 x 112-17 x eKMx(K)

Encrypted key - Triple-length - ECB



2-25 x eKMx(K)

Encrypted key - Double-length CBC



2-17 x eKMx(K)

Encrypted key Triple-length CBC



2-25 x eKMx(K)

The following key specifier format supports the storage of key attributes. Note an IV of all zeros isused 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 01Key Type 1 h 00 = RFU

01 = Interchange keyKey sub-type 1 h 00, unless otherwise specified for a

particular Key Type.For Key Type = 01:00 = RFU01 = KIS02 = KIR

KM-Id 1 h Identifies the KM (applies to AMBHSM) used with the authenticationalgorithm, otherwise must be zero.

Authentication

Algorithm Id.

1 h 01 = 3DES CBC 64-bit MAC

SafeNet, Inc. 17


27/522




Attribute Count 1 h Number of attributes02 for KIS/KIR keys

Padding 1 h 00

eKMv20(K) Var h 3DES CBC-encrypted key.IV = bytes 1 8 of key specifier.KIS/KIRAttributes

See below Number related to Attribute Count.(See KIS/KIR Attributes below)

MAC 8 h Authentication code calculated onprevious fields, using variant 19 of KMand the algorithm specified inAuthentication Algorithm Id.

The following table lists KIS/KIR Attributes for Format 15.

Attribute Len Attribute Description

Number

1 1 h Variant Scheme00 none01 Eracom02 Atalla03 AS2805.6.3 2000

2 1 h 00 functions enabled01 functions disabled (only set whenvariant type = 00 )

DBL, Triple Length PermittedThe following key specifier format explicitly incorporates algorithms and other parametersassociated with the key.

Encrypted key Algorithm included


Format 16 1 h 16Algorithm 1 h Algorithm

E0 = SEEDKey length 1 h Key length

02 = 128Block length 1 h Block Length

02 = 128Mode ofoperation

1 h Mode of Operation01 = ECB

02 = CBCeKMv(K) Var h Encrypted key

The following key specifier format supports a complete ANSI TR-31 Key Block.

Variants of the KM are used as the encryption key and the MAC key for host stored keys.Variants of the KTM are used as the encryption key and the MAC key for terminal destined keys.

SafeNet, Inc. 18


28/522




Format 17 1 h 17KM-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 4of the Block header.

The following key specifier format supports an ANSI TR-31 Key Block using binary fields insteadof 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 BinaryKey Block to be converted to a TR-31 key Block (or vice versa) with no change to the value of theMAC.

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



Format 18 1 h 18KM-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 isidentical Format 17 described above,with the exception that the encryptedkey field and the MAC field are stored in

binary and not expanded to hex-ASCII.The Key Block Length in bytes 1-4 ofthe Secure Key Block, however, is thelength of the equivalent TR-31 KeyBlock (that is the length that wouldoccur following the expansion to hex-ASCII).

The following key specifier format supports a CAP Bitmap. The CAP Bitmap specifier is anauthenticated data structure containing a payload in the clear. Although the CAP Bitmapspecifier does not contain a key, it is implemented as a key specifier, as the key specifier format iseasily extended to hold CAP Bitmap data.

The data specifier incorporates a header, a payload and an authentication code. The headerindicates the format of the payload. The present implementation only supports payload data thatis not encrypted.

With the exception of the header (first 8 bytes) and the final field (8-byte authentication code) thecomplete contents of the data specifier may be CBC-encrypted with KMv20, with the headerutilized as the IV. An IV of all zeros is used in the formation of the Authentication Code.

Host-stored bitmap


Format 19 1 h 19Data SpecifierType

1 h = 02 CAP Bitmap

SafeNet, Inc. 19


29/522


Host-stored bitmap


EncryptedPayload

1 h = 00 - payload is not encrypted

KM-Id 1 h For the AMB HSM, identifies the KM

used, otherwise must be zero.Payload Length 2 h = 0008Pad1 2 h = 0000Bitmap 8 h Field from IPBAuthenticationCode

8 h 3DES CBC 64-bit MAC calculated onall 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 preventsthe 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 attributesField Content Length Attribute Description

Format 20 1 h 20BDK 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) suppliedby pin pad

Derived Key Type 1 h Specifies the length of the transactionkey0x02= double length (TDEAtransaction key is derived) and thevariant constant indicator will be used

for request or both ways.0x12= variant constant indicator willbe used for response.

This key specifier calculates a unique-per-card derived key. It is used to derive KKEK (as defined in[Reference [32] for Mark II]) so that the key may be used to encrypt a key or sensitive data to besent to the card. CardMethod (01 or 02) define the mode of encryption.

Unique-per-card derived key


Format 50 1 h 50KMC Var K-Spec Key specifier for personalization master

key (format 0 3, 13).Card-uniquederivation data

16 h

Card method 1 h = 01: ECB= 02: CBC

This key specifier calculates a unique-per-card derived session key. It is used to derive SKUENC,SKUMAC (as defined in [32] and [33] for MarkII]) in support of the mutual authentication of thecard being personalized and its host. CardMethod (01 or 02) and SessionMethod (01 or 02) definethe mode of encryption.

SafeNet, Inc. 20


30/522


Unique-per-card derived session key


Format 51 1 h 51KMC Var K-Spec Key specifier for personalization master

key

(format 0 3, 13).Card-uniquederivation data

16 h

Card method 1 h = 01: ECB= 02: CBC

Session data 16 hSession method 1 h = 01: ECB

= 02: CBC

The following formats for the key specifier structure support the host-storage of RSA public andprivate keys. A public key is stored in a clear form, with or without an authentication value, whilea private key is stored encrypted by a variant of KM.

In accordance with existing HSM convention, multi-byte integers (modulus and exponent) arestored with the leftmost byte containing the most-significant bits (i.e. big-endian).

RSA public key Clear, unauthenticated


Format 80 1 h 80Modulus Var h Modulus of RSA public key.

Var h Exponent of RSA public key.len(Exponent) len(Modulus)

Exponent

No leading zeros

This key specifier will be supported by the KM-MIGRATE function, to translate AuthenticationValuefrom an old KM to the current KM.

RSA public key Clear, authenticated


Format 1 h 81Modulus Var h Public key modulus.Exponent Var h Public key exponent.

len(Exponent) len(Modulus) Leadingzeroes need not be included.

KM-Id 1 h For the AMB HSM, identifies the KM used withthe authentication algorithm, otherwise must bezero.

Key Type 2 h Key Type attribute bits

AuthenticationAlgorithm Id.

1 h = 01 3DES CBC 64-bit MAC

User data Var h Optional user data.AuthenticationValue

Var h Authentication value calculated using variant19 of KM and the algorithm specified inAuthentication Algorithm Id.

This key specifier will be supported by the KM-MIGRATE function, to translate eKMv20(SK)andAuthentication Value from an old KM to the current KM.

SafeNet, Inc. 21


31/522


RSA private key Encrypted


Format 1 h 82Mod Len 2 h Length of modulus (m) in bytes.Key format 1 h Format of the encrypted key field.

= 01: Eracom default format.KM-Id 1 h For the AMB HSM, identifies the KM used to

encrypt the private key and with theauthentication algorithm, otherwise must bezero.

Key Type 2 h Key Type attribute bitsAuthenticationAlgorithm Id.

1 h = 01: 3DES CBC 64-bit MAC

User data Var h Optional user data.eKMv20(SK) Var h Private key, encrypted with variant 20 of KM.

Plaintext format of SK prior to encryption definedelsewhere, and not necessarily for generalpublication.

AuthenticationValue

Var h Authentication value calculated using variant19 of KM and the algorithm specified inAuthentication Algorithm Id.

The following Key Specifier Format specifies the format for a ZKA Random Number. This keyspecifier incorporates the data required to produce a clear PAC or MAC session key. A PAC key isproduced if the key specifier is used within a PIN management function and a MAC key isproduced if the key specifier is used within a message authentication function. It can alsoincorporate a format 92 key specifier as theMK-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-specrequest field in standard functions. Specifically, the following functions will support a ZKA-RNDformat 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


Format 1 h = 90

MK-spec Var K-spec Key specifier for Master key(formats 03, 13, 92).

CV-index 1 h 0 = use values in ZKA

documentation;>0 = use HSM-stored CV values

RND 16 h Random Number (Encrypted SessionKey eTK(KS))

The CV values defined in ZKA documentation may be overridden by CV values stored within theHSM.

The following Control Vector values are used when constructing a format 90 host stored keyspecifier. Key values for each type are defined below.

Type CV1 CV2

MAC 00 00 4D 00 03 41 00 00 00 00 4D 00 03 21 00 00

SafeNet, Inc. 22


32/522


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 specifierincorporates the data required to derive a *KKBLZ as follows:

*KKBLZ = e*KGK1(BLZ | BLZ) | e*KGK2(BLZ | BLZ)

The key specifier may be used in the functions that contain a '*KK-spec' field, i.e. 'ZKA-PIN-VER ecPVN method ' and 'ZKA-Calculate PVN from encrypted PIN'

ZKA-Derived-*KK


Format 1 h = 91

*KGK1-spec Var K-spec Key specifier for *KGK1(formats 0-3 or 13)

*KGK2-spec Var K-spec Key specifier for *KGK2

(format 0-3 or 13)BLZ 4 h 00000000 - FFFFFFFF

The following Key Specifier Format specifies the format for a ZKA-MK2 key. This key specifier isused 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 Datefield indicates that the field value has not been specified. The permissible omitted fields areindicated in the usage context of the key specifier.

Specification of Sub-type Number, Version Number and Generation Number unambiguouslyreferences 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. Thesearch criteria are specified in the context where the key specifier is used.

MK2 reference


Format 1 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;

or mmyy = 9999

The following Key Specifier Format (1A) specifies the format for carrying a KM-encrypted PIN.

The Domain Master Key (KM) and its variants are typically used to protect other keys. Modernusage of the KM has involved the key specifier function field. Consistent with this usage, the KM-encrypted PIN comprises a formatted PIN Block that is encrypted using a dedicated variant of KMand 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 theresulting cipher text Block has a length of 8 bytes.

SafeNet, Inc. 23


33/522


Use of ISO format 3 implies that the 12-digit Account Number Block (ANB) must be suppliedwhen the PIN is generated, and whenever the KM-encrypted PIN is subsequently used.

KM variant 27 is used for PIN-Block encryption to produce a KM-encrypted PIN for host storage.The hexadecimal constant associated with KMv27 is X74.

KM-encrypted PIN


Format 1 h = 1A

Type 1 h = 01

KM-Id 1 h For the AMB HSM, identifies the KM used,otherwise must be zero.

8 h Encrypted PIN Block.eKMv27(PIN)

Usage Notes for Key Specifiers In Host Functions

The key specifier is widely used in newly developed host functions. The type of key being accessedby the key specifier will most likely always be implicit in the function design. For example, in oneplace a key specifier might be for a terminal master key, in another place it could be for PINverification key, and in yet another it could be for a PIN encrypting key. This is identical to thecurrent 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 anindex to a HSM-stored key.

When considering key specifier formats, the following guidelines apply:

- Formats 0,1,2 or 3 should be used when specifying an index to a HSM stored key.

- Format 10 should be used to specify single-length, host stored keys that are encrypted usingECB.

- Format 11 is provided as legacy function support. Some older functions used ECB instead ofCBC 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 tohave been generated using these legacy functions. New functions use CBC to encrypt double-

length keys and Format 13.

- Format 13 should be used to specify double-length, host stored keys that are encrypted usingCBC.

- Format 14 should be used to specify triple-length, host stored keys that are encrypted usingCBC.

- HSM-stored (formats 0-3) MPK keys can be stored for use with DES or HMAC-SHA-1algorithm. HMAC-SHA-1 MPK key valid key lengths are 128, 160 and 192 bits. DES MPKkey 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.

SafeNet, Inc. 24


34/522


PIN Block Formats

Supported PIN Block Formats

The format of a PIN Block is specified in a single-byte field. The valid values for the field and the

associated meanings are shown in the following table.

Format Name Details

01 ANSI 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 initiallypadded to the right with 2 or 1 zero digits tototal 6 digits.

02 Docutel 2

03 PIN/Pad Identical to existing PIN-TRAN Format 3.08 Docutel Identical to existing Docutel 5100 Format 8

(used in D51-PIN-TRAN, etc.)09 ZKA The input PIN Block may be ISO Format 0 or an ISO Format 110 ISO 0 Identical to Format 01 above.11 ISO 1 ISO 9564-1:2003 Format 112 ISO 2 ISO 9564-3: 2003 Format 213 ISO 3 ISO 9564-1: 2002 Format 3

A particular function may not support all of the formats identified above. The specification of eachfunction identifies which formats it supports.

Note: Functions that translate PIN, output PIN block format can be 09 only if input PIN blockformat is 09.

Restrictions on reformattingIn those PIN translate functions that support the reformatting of the PIN block from one format toanother, disassociation of the PIN from the Account Number is prevented by the followingrestrictions on the reformatting that is supported.

PIN Block Format Reformatting supportedISO-0 / ANSI ISO-3

ISO-1 ISO-0, ISO-3ISO-2 ISO-0, ISO-1, ISO-3ISO-3 none

PIN/Pad ISO-0, ISO-1, ISO-3

Docutel ISO-0, ISO-1, ISO-3

A console operation allows the user to modify the above default reformatting rules.

Enabled and Disabled PIN Blocks

The HSM needs to support all PIN blocks formats that are used within the industry. Many users donot require support for some of these formats. Therefore, each PIN block format can be enabled ordisabled. The default condition for each PIN block format is as follows.

PIN Block Format Enabled DisabledISO-0 xISO-1 xISO-2 xISO-3 x

SafeNet, Inc. 25


35/522


SafeNet, Inc. 26

PIN/Pad xDocutel x

A console operation allows the user to enable support for just those PIN block formats that arerequired.

Function Identifier ControlThe Function Identifier Control allows the HSM to operate with a new optional Function Identifierfield which is placed into the function request and response messages in order to provide messageidentity.

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 responsemessage. 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 ordeactivate the function identifier.

Message Meta-function FormatThe meta-function message format provides a transparent mechanism for implementingextensions to the current host message format. See Chapter 3, The Metafunction for furtherinformation.


36/522

Mark IIProgrammers Guide Chapter 3The Metafunction

SafeNet, Inc. 27

Chapter 3The Metafunction

Message Meta-function FormatThe meta-function message format provides a transparent mechanism for implementingextensions to the current host message format.

Note: Currently, only SafeNets ProtectToolkit EFT product makes use of the meta-functionformat. Metafunction support can be enabled or disabled via the console under the DeviceAdministration/Function Control menu.

The meta-function is presented as a special function code called the Meta-function Indicator (E3). If

the Meta-function Indicatoris found in the message, the SHP knows that the message cameencapsulated. It then extracts the normal request message frame, processes it in the usual mannerand then puts the meta-function back around the response message before sending the reply.

Request Message

CommsHeader

Meta-functionIndicator

Meta-functionType

Version Type specificdata

Comms trailer

Response Message

CommsHeader


Meta-functionType

Version Response Code(= 00)

Type specificdata

Comms trailer

Meta-function Error Response Message

CommsHeader


Meta-functionType

Version ResponseCode( 00)

Type specificdata

Comms trailer

A meta-function request could incorporate a normal request message as a variable-length fieldwithin its request data (i.e. type specific data) or it could contain another meta-function as thevariable-length field.

Two Meta-function types are presently defined. If the byte following the Meta-function Indicatorbyteis not one of the defined types, the HSM returns a Meta-function Error Response message withResponse Code = 01.

The Version field allows the format of the meta-function to change over time in a manner thatprovides backward compatibility.

The Response Code field allows for error reporting for the meta-function header fields. Thistranslates to a meta-function with a variable-length field that has a zero length (instead ofcontaining 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.


37/522


Metafunction PHW DSHP D

PSO/PSG U SHP Toolki t MK2 U

Card Issuance (SHP Toolki tEMV)

D

Request Content Length DescriptionAttributeE3 1 h Function Code

Reserved Byte 1 h Reserved currently 00Meta-function ID 1 h Meta-function type identifier

Version 1 h Meta-function type versionMessage Id 4 x A Message Id used by cryptolinkData Field Var x Normal request message

( or meta-function request)Response Content Length DescriptionAttribute

E3 1 h Function Code

Reserved Byte 1 h Reserved currently 00Meta-function ID 1 h Meta-function type identifier

Version 1 h Meta-function type versionReturn Code 1 h A return code that indicates the

status of the sent functionMessage Id 4 x A message Id used by cryptolinkData Field Var x Normal request message

(or Meta-function request)

The meta-function message format provides a transparent mechanism for implementingextensions to the current host message format. When used with SafeNets Cryptolink product, itprovides a unique message identifier for all messages.

Reserved Byte Currently restricted to 00

eta-function ID Meta-function type00The 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 useas a heartbeat function when used with ProtectToolkit EFT.

Meta-function type 01The 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 01The version field allows for the format of the meta-function to evolve overtime 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 theresponse message.

Not used when Meta-function Id = 00

SafeNet, Inc. 28


38/522


Data The data field is a var field which in the request contains the encapsulatedmessage request and in the response contains the encapsulated response.Not used when Meta-function Id = 00

Return Codes:

00 OK01 Invalid meta-function Id02 Invalid version number03 Invalid data field length

NOTE

If an error occurs in the E3 Function the encapsulated message is notrun and no return data will be presented.

SafeNet, Inc. 29


39/522


SafeNet, Inc. 30


40/522

Mark IIProgrammers Guide Chapter 4HSM Status Functions

SafeNet, Inc. 31

Chapter 4HSM Status Functions

Summary of HSM Status Functions

Function Name Function Code Page

HSM_STATUS 01 32

HSM-ERRORLOG-STATUS FFF0 34

HSM-GET-ERRORLOG FFF1 36

The Error LogThe error log consists of one or more text files stored on the hard disk of the HSM. If an errorcondition is generated by the HSMs software that error condition is written to the HSMs errorlog. The error number, line of code and module being run are the details recorded for each errorwhen it occurs.

The error log is not an audit trail and does not record details of functions run, function data, keyssaved or key data.

safenet programmers guid

Documents