Safenet Programmers Guid

(1)

(2)

Mark II Programmers Guide Copyright

Copyright

All intellectual property is protected by copyright. All trademarks and product names used or referred to are the copyright of their respective owners. No part of this document may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic, mechanical, chemical, photocopy, recording or otherwise without the prior written permission of SafeNet.

SafeNet makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Furthermore, SafeNet reserves the right to revise this publication and to make changes from time to time in the content hereof without the obligation upon SafeNet to notify any person or organization of any such revisions or changes.

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

SafeNet, Inc.

4690 Millennium Drive Belcamp, Maryland 21017 USA

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

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

Part Number 003198-002, Revision T Software versions 1.1

Revision Action/Change Date

O This revision was skipped for Document Control reasons.

June 2009 P SHP 1.1 Release. MarkII Programmer’s Guide

updated for:

June 2009 1. Card Issuance Integration

2. 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.

(3)

Mark II Programmers Guide Copyright

Certifications

FCC Compliance

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

FCC Notice to Users

These limits are designed to provide reasonable protection against harmful interference in a residential installation. This equipment generates, uses and can radiate radio frequency energy and if not installed and used in accordance with the instructions, may cause harmful interference to radio communications. However, there is no guarantee that interference will not occur in a particular installation. If this equipment does cause harmful interference to radio or television reception, which can be determined by turning the equipment off and on, the user is encouraged to try to correct the interference by one or more of the following measures:

Reorient or relocate the receiving antenna.

Increase the separation between the equipment and receiver.

Connect the equipment into an outlet on a circuit different from that to which the receiver is connected. Consult the dealer or an experienced radio/TV technician for help.

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

WEEE and RoHS Compliance

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

(4)

Mark II Programmers Guide Table of Contents

Preface

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

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

Where to Find Information ?

Information Recommended References

MarkII 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 Appendices under Part 3 of the Guide

Appendix A - IBM 3624 PIN Verification Method Appendix B - EFT Terminal Functions

Appendix C - Card Issuance Function Examples Appendix D - PIN Management Function Examples Appendix E - EMV Function Examples

Appendix F - American Express Account Blocks Appendix G - American Express Examples Appendix H - Function Matrix (MarkII) Appendix I - SHP Toolkit

Appendix J - Error Codes Appendix K - References Appendix L - Glossary Appendix M - Function list

Contacting Technical Support

If you encounter a problem while installing, registering or operating this product, please make sure that you have read the documentation. If you cannot resolve the issue, please contact your supplier or SafeNet support. SafeNet support operates 24 hours a day, 7 days a week. Your level of access to this service is governed by the support plan arrangements made between SafeNet and your organization. Please consult this support plan for further information about your entitlements, including the hours when telephone support is available to you. Technical Support Contact Information:

Phone: 800-545-6608

(9)

(10)

Mark II Programmers Guide

Part 1

______________________________________________________________________

(11)

(12)

Mark II Programmers Guide Chapter 1 Introduction

Chapter 1 Introduction

Overview

This Guide covers standard Mark II and Card Issuance functionality. It provides a complete function reference for all functions that make up the Mark II and Card issuance function set. These function sets, which are supported on SafeNet Hardware Security Modules (HSMs), may be utilized by EFT network designers to implement a variety of key and PIN management schemes. Mark II and Card Issuance functions are available as standard on the following SafeNet HSM products. These are the;

• ProtectHost EFT (referred to as SHP, hereafter) • ProtectHost White Mark II

• ProtectHost White Card Issuance • ProtectServer Orange

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

Additionally, further functions may also be available.

• SafeNet also develops custom functions to meet the specific needs of particular customers. Details can be found in a customization guide supplied with the product, where applicable. The SHP product provides an application programming interface in the ‘C’ programming

language. SHP Toolkit MK2, is a component within this product, that allow third parties to easily interface to the SHP, HSM and ProtectServer Orange security modules running the MarkII and Card Issuance software. The SHP Toolkit MK2 is also described in this Guide.

(13)

Product Architecture

Design Paradigm

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

Implementation

Using the ProtectToolkit EFT APIs

It is possible to simplify system implementation by making use of the SafeNet product

ProtectToolkit EFT. ProtectToolkit EFT offers host applications all of the available functions on the ProtectHost White Card Issuer HSM, in C callable form. The ProtectToolkit EFT product is made up of two application programming interfaces (APIs), SHP Toolkit CI and SHP Toolkit MK2. This is shown in the diagram below.

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

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

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

Common Terms and Phraseology

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

Encryption Notation

The notation used for encryption and decryption is as follows: eK(D) where data D is encrypted under the key K. dK(D) where data D is decrypted with the key K.

(14)

Supplemental Documentation

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

• MarkII Installation Guide - SHP • MarkII Console User Guide • HSM Software Loader Help For Customizations:

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

Host Function Overview

Each function involves a host request being sent to the HSM. Each request produces a

corresponding response message containing the results of the function or a status code indicating an error. The message content of each function is described in this guide and is independent of the selected communications protocol. Message formatting procedures appropriate to each available protocol are described in the Communications Guide.

A host request message starts with a Function Code followed by function-dependent binary data. These data may be fixed or variable length depending on the function. Functions requiring variable length data include the length of the variable field in a one-byte length parameter. Where a function requires multiple fields in a message, there is no delimiter between fields.

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

eKM1(KSn) = 12 34 56 78 90 AB CD EF By adding the function code the complete host request message is

44 12 34 56 78 90 AB CD EF

A response message starts with the Function Code from the host request message followed by a one-byte Return Code. Appendix I Error Codes lists the assignments for the Return (Error) Code. If the Error Code returned is non-zero, there is no data following the Error Code. Otherwise, the response data follows the Error Code.

For example, function NT-PPK-GEN (FN 44):

Return Code : 0A (uninitialized key access) By adding the function code the complete response message is

44 0A

Host Function Specification in this Guide

For each Host Function that is specified in this document, the title of the section which details the specification takes the following format.

(15)

HSM product running the Card Issuance software. A

D

indicates that the function is supported in the product. A U indicates that it is not supported in the product.

The specification of the function follows the title. For those functions that are supported in the SHP Toolkit MK2, the function definition is provided following the specification, as illustrated below.

(16)

Mark II Programmers Guide Chapter 2 Function Construction

Chapter 2 Function Construction

Host Function Overview

Each function involves a host request being sent to the HSM. Each request produces a

corresponding response message containing the results of the function or a status code indicating an error. The message content of each function is described in this guide and is independent of the selected communications protocol. Message formatting procedures appropriate to each available protocol are described in the Communications Guide.

A host request message starts with a Function Code followed by function-dependent binary data. These data may be fixed or variable length depending on the function. Functions requiring variable length data include the length of the variable field in a one-byte length parameter. Where a function requires multiple fields in a message, there is no delimiter between fields.

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

eKM1(KSn) = 12 34 56 78 90 AB CD EF By adding the function code the complete host request message is

44 12 34 56 78 90 AB CD EF

A response message starts with the Function Code from the host request message followed by a one-byte Return Code. Appendix J Error Codes lists the assignments for the Return (Error) Code. If the Error Code returned is non-zero, there is no data following the Error Code. Otherwise, the response data follows the Error Code.

For example, function NT-PPK-GEN (FN 44) :

Return Code : 0A (uninitialized key access) By adding the function code the complete response message is

44 0A

Function Message Formats

Data Item Representation in Request/Response Messages

Request and response content may use the following operators and qualifying letters. Operator Meaning

(17)

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

Function Modifier Values

Selection of host key protection method within host functions can be done using the FM field. The Host Key Protection using Function Modifier can be in the range of x0, where x= 0 , 1 or 2. This impacts the key-types under the Response Content since they are generated based on the chosen operation on console and FM. The following table shows different combinations of FM value and console check box and their impact on behavior of the host function.

Notes:

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

(18)

Mark II Programmers Guide Chapter 2 Function Construction State of FM Override on console Global Method Selected

FM xy Key Protection Method to be used

Enabled Legacy 0000 0000 Legacy method Legacy 0001 0000 ECB method Legacy 0010 0000 CBC method ECB 0000 0000 ECB method ECB 0001 0000 ECB method ECB 0010 0000 CBC method CBC 0000 0000 CBC method CBC 0001 0000 ECB method CBC 0010 0000 CBC method Disabled Legacy 0000 0000 Legacy method

Legacy 0001 0000 Error (conflict with global method).

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

Error code : : 0x24 FN_INVALID_FN_MODIFIER ECB 0000 0000 ECB method

ECB 0001 0000 ECB (No conflict with global method) ECB 0010 0000 Error (conflict with global method).

Error code : : 0x24 FN_INVALID_FN_MODIFIER CBC 0000 0000 CBC method

CBC 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 Response

Messages

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

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

Length of length prefix Length indicator bits in most significant byte (bytes)

1 0… 2 10…

3 110 …

(19)

Mark II Programmers Guide Chapter 2 Function Construction 1 00 – 7F 00 – 7F 0 – 127 2 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 function request or request message, with an indicated length of ‘Var’. Therefore, there is no need to indicate the length as a separate field.

• The length prefix indicates the length of the data portion of the field, i.e. the length prefix is not included in the length. The specified length is a number of bytes.

• The length prefix is independent of the attributes and contents of the data value.

• For multi-byte length prefixes, the byte order in the field is most significant byte first, i.e. big endian. This is in line with the general rule for all multi-byte integer fields in Mark II functions.

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

• For variable-length fields in response messages, the length prefix consists of the minimum number of bytes required to express the data length of the field.

• A variable-length field with a data length of zero is represented entirely by a length prefix containing the value zero, e.g. X’00’ or X’8000’. A zero-length field is useful where a field is not optional, but is not used.

(20)

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

ms b 1s b

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

ms b 1s b ms b 1sb

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)

(21)

Four byte length

First byte transmitted Second byte transmitted Third byte transmitted Fourth byte transmitted

ms b 1s b ms b 1sb ms b 1sb ms b 1sb

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 b05 b04 b03 b02 b01 b00

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

(22)

Variants

KM Variants

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

Variant Value Used to encrypt:

0 X’00’ DPK 1 X’28’ PPK 2 X’24’ MPK 3 X’44’ KIS 4 X’88’ KIR 5 X’22’ KTM 6 X’20’ CSCK 7 X’18’ KPV, DT 8 X’14’ KPVV 9 X’48’ KCVV

10 X’45’ Key Block encryption - terminal

11 X’4D’ Key Block message authentication –terminal

14 X’5C’ KTPV

16 X’0C’ KGK

17 X’0A’ KKBLZ

18 X’1E’ MK-ZKA

19 X’2E’ MAC used for Format 15 host stored keys 20 X’4E’ (K) used for Format 15 host stored keys

24 X’72’ BDK

25 X’78’ Key Block encryption – host

26 X’70’ Key Block message authentication – host 27 X’74’ PIN Block encryption – KM encrypted PIN

30 X’30’ IMK-AC 31 X’36’ IMK-SMI 32 X’3A’ IMK-SMC 33 X’3C’ IMK-DAC 34 X’50’ IMK-IDN 35 X’66’ KTK 36 X’6A’ PTK 37 X’6C’ KMC 38 X’7E’ IMK-CVC

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

SafeNet Variant Scheme

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

(23)

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 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 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 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 Used to Protect Byte DPK X'22' X'24' MPK PPK X'28'

Size of Session Key Method

The variant constant is obtained by repeating the Variant Byte from the above table to yield an 8 byte constant. 64-bit DEA keys

The variant constant is obtained by concatenating the variant byte from the above table with the constant xC0 and repeating these 2 bytes 8 times to yield a 16 byte constant. 128 bit CBC and DEA keys

The variant constant is obtained by concatenating the variant byte from the above table with the constant x30 and repeating these 2 bytes 12 times to yield a 24 byte constant. 192 bit CBC and DEA keys '

(24)

Public Key Verification Code

The KVC for a public key (PVC) is formed as described in AS2805 part 6.1 as follows:

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

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

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

The ‘Key Specifier’ Function Field

Host functions utilize two field constructs, namely the Variable-length field and the Key specifier. The key specifier construct is a variable-length field that contains a variable-format specification of a key. In general, a key specifier may contain either an index to an HSM-stored key, or an encrypted key from host storage – encrypted by a variant of *KM. The format of a key specifier field is fully described in this section. Formats for key specifiers that accommodate RSA public and private keys are also covered.

Most host functions perform transformations using cryptographic keys which are stored either within the secure memory (HSM-stored) or in the host database in encrypted form (Host-stored). Traditionally, the choice of whether a key should be HSM-stored or host-stored has been on a per-key-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.

(25)

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 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

(26)

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

2-9 x eKMx(K)

Encrypted key - Double-length - ECB

2-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 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

(27)

Field Content Length Attribute Description Attribute Count 1 h Number of attributes

02 for KIS/KIR keys

Padding 1 h 00

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

Attributes

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

MAC 8 h Authentication code calculated on

previous fields, using variant 19 of KM and the algorithm specified in

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

Attribute Len Attribute Description Number 1 1 h _{Variant Scheme} 00 none 01 Eracom 02 Atalla 03 AS2805.6.3 2000 2 1 h 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

Format 16 1 h 16

Algorithm 1 h Algorithm

E0 = SEED

Key length 1 h Key length

02 = 128

Block length 1 h Block Length

02 = 128 Mode of operation 1 h Mode of Operation 01 = ECB 02 = CBC

eKMv(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.

(28)

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

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.

(29)

Host-stored bitmap

Field Content Length Attribute Description Encrypted

Payload

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 = 0008

Pad1 2 h = 0000

Bitmap 8 h Field from IPB

Authentication Code

8 h 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.

Format 20 1 h 20

BDK Var K-spec Key specifier for the Base Derivation Key (BDK). (Formats 0-3, 13, 14 ) KSN 10 h Key serial number (= Initial key serial

number + Encryption counter) supplied by pin pad

Derived Key Type 1 h Specifies the length of the transaction key

0x02= double length (TDEA transaction key is derived) and the variant constant indicator will be used for request or both ways.

0x12= variant constant indicator will be used for response.

This key specifier calculates a unique-per-card derived key. It is used to derive KKEK (as defined in

[Reference [32] for Mark II]) so that the key may be used to encrypt a key or sensitive data to be sent to the card. CardMethod (01 or 02) define the mode of encryption.

Unique-per-card derived key

Format 50 1 h 50

KMC Var K-Spec Key specifier for personalization master key (format 0 –3, 13).

Card-unique derivation 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 SKU_ENC, SKUMAC (as defined in [32] and [33] for MarkII]) in support of the mutual authentication of the

card being personalized and its host. CardMethod (01 or 02) and SessionMethod (01 or 02) define the mode of encryption.

(30)

Unique-per-card derived session key

Format 51 1 h 51

KMC Var K-Spec Key specifier for personalization master key

(format 0 –3, 13). Card-unique

derivation data

16 h

Card method 1 h = 01: ECB

= 02: CBC

Session data 16 h

Session method 1 h = 01: ECB

= 02: CBC

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

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

RSA public key – Clear, unauthenticated

Format 80 1 h 80

Modulus 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 Authentication Value from an old KM to the current KM.

RSA public key – Clear, authenticated

Format 1 h 81

Modulus Var h Public key modulus.

Exponent Var h Public key exponent.

len(Exponent) • len(Modulus) Leading zeroes need not be included.

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

Key Type 2 h Key Type attribute bits Authentication

Algorithm Id.

1 h = 01 3DES CBC 64-bit MAC User data Var h Optional user data.

Authentication Value

Var h Authentication value calculated using variant 19 of KM and the algorithm specified in Authentication Algorithm Id.

(31)

RSA private key – Encrypted

Format 1 h 82

Mod 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 the

authentication algorithm, otherwise must be zero.

Key Type 2 h Key Type attribute bits Authentication

Algorithm 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 defined elsewhere, and not necessarily for general publication.

Authentication Value

Var h Authentication value calculated using variant 19 of KM and the algorithm specified in Authentication Algorithm Id.

The following Key Specifier Format specifies the format for a ZKA Random Number. This key specifier incorporates the data required to produce a clear PAC or MAC session key. A PAC key is produced if the key specifier is used within a PIN management function and a MAC key is produced if the key specifier is used within a message authentication function. It can also incorporate a format 92 key specifier as the MK-spec, in order to access a key in the MK2 table. This key specifier format can also be used as an alternative format in a PPK-spec or MPK-spec request field in standard functions. Specifically, the following functions will support a ZKA-RND format key specifier:

• MAC-UPDATE, MAC-GEN-FINAL, MAC-VER-FINAL • PIN-TRANSLATE

• PIN-VERIFY, Calculate IBM Offset, MIGRATE-PIN

• PIN Verify – PVV, Calculate PVV from IBM Offset, Calculate PVV from PIN Encrypted session key

Format 1 h = 90

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

CV-index 1 h 0 = use values in ZKA

documentation;

>0 = use HSM-stored CV values

RND 16 h Random Number (Encrypted Session

Key eTK(KS))

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

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

Type CV1 CV2

(32)

PAC 00 21 5F 00 03 41 00 00 00 21 5F 00 03 21 00 00

The following Key Specifier Format specifies the format for a ZKA-Derived-*KK. This key specifier incorporates the data required to derive a *KKBLZ as follows:

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

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

ZKA-Derived-*KK

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 is used to reference an MK in the MK2 table.

A value of X'FF' in any of the 'h' attribute fields or a value of 9999 in the 'd' attribute Expiry Date field indicates that the field value has not been specified. The permissible omitted fields are indicated in the usage context of the key specifier.

Specification of Sub-type Number, Version Number and Generation Number unambiguously references a specific record in the MK2 table.

Alternatively (for example), Version Number and / or Generation Number may be set to X'FF' and / or Expiry Date may be set to 9999 to indicate that a search of the table should be performed. The search criteria are specified in the context where the key specifier is used.

MK2 reference

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. Modern

(33)

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’.

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 accessed by the key specifier will most likely always be implicit in the function design. For example, in one place a key specifier might be for a terminal master key, in another place it could be for PIN verification key, and in yet another it could be for a PIN encrypting key. This is identical to the current situation with indexes to HSM-stored keys.

The function field therefore always identifies the type of key that the key specifier is for. It will not always be appropriate for a given key type to be HSM-stored or host-stored. Nevertheless, a key specifier is still useful, e.g. to provide a choice of formats for specifying an index to a HSM-stored key.

When considering key specifier formats, the following guidelines apply:

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

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

- Format 11 is provided as legacy function support. Some older functions used ECB instead of CBC to encrypt a double-length key for host storage.

Note that this key specifier should only be used to supply host stored keys that are known to have been generated using these legacy functions. New functions use CBC to encrypt double-length 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-HMAC-SHA-1 algorithm.

(34)

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 initially padded to the right with 2 or 1 zero digits to total 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 1 10 ISO 0 Identical to Format 01 above.

11 ISO 1 ISO 9564-1:2003 Format 1 12 ISO 2 ISO 9564-3: 2003 Format 2 13 ISO 3 ISO 9564-1: 2002 Format 3

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

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

Restrictions on reformatting

In those PIN translate functions that support the reformatting of the PIN block from one format to another, disassociation of the PIN from the Account Number is prevented by the following restrictions on the reformatting that is supported.

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

ISO-1 ISO-0, ISO-3

ISO-2 ISO-0, ISO-1, ISO-3 ISO-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

(35)

PIN/Pad x

Docutel x

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

Function Identifier Control

The Function Identifier Control allows the HSM to operate with a new optional Function Identifier field which is placed into the function request and response messages in order to provide message identity.

When enabled, the Function Identifier is a fixed-length field with length as specified by the user, occurring immediately after the function code field in every function request and response message. Field length can be set in a range from 1 to 99 bytes in length.

To maintain backwards compatibility, the function identifier can be switched on or off via a console operation. Please refer to the console user guide for details on how to activate or deactivate the function identifier.

Message Meta-function Format

The meta-function message format provides a transparent mechanism for implementing extensions to the current host message format. See Chapter 3, The Metafunction for further information.

(36)

Mark II Programmers Guide Chapter 3 The Metafunction

Chapter 3 The Metafunction

Message Meta-function Format

The meta-function message format provides a transparent mechanism for implementing extensions to the current host message format.

Note: Currently, only SafeNet’s ProtectToolkit EFT product makes use of the meta-function format. Metafunction support can be enabled or disabled via the console under the Device Administration/Function Control menu.

The meta-function is presented as a special function code called the Meta-function Indicator (E3). If the Meta-function Indicator is found in the message, the SHP knows that the message came

encapsulated. It then extracts the normal request message frame, processes it in the usual manner and then puts the meta-function back around the response message before sending the reply.

Request Message

Comms Header Meta-function Indicator Meta-function Type

Version Type specific data … Comms trailer

Response Message

Comms Header Meta-function Indicator Meta-function Type Version Respons e Code (= 00) Type specific data … Comms trailer

Meta-function Error Response Message

Comms Header Meta-function Indicator Meta-function Type Version Response Code (<> 00) Type specific data … Comms trailer

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

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

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

(37)

Metafunction

PHW

D

SHP

D

PSO/PSG

U

SHP Toolkit MK2

U

Card Issuance (SHP Toolkit

EMV)

D

Request Content Length Attribute Description

E3 1 h Function Code

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

Version 1 h Meta-function type version Message Id 4 x A Message Id used by cryptolink

Data Field Var x Normal request message ( or meta-function request)

Response Content Length Attribute Description

E3 1 h Function Code

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

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

status of the sent function Message Id 4 x A message Id used by cryptolink

Data Field Var x 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.

(38)

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

Return Codes: 00 OK

01 Invalid meta-function Id 02 Invalid version number 03 Invalid data field length

NOTE

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

(39)

(40)

Mark II Programmers Guide Chapter 4 HSM Status Functions

Chapter 4 HSM Status Functions

Summary of HSM Status Functions

Function Name Function Code Page

HSM_STATUS 01 32

HSM-ERRORLOG-STATUS FFF0 34

HSM-GET-ERRORLOG FFF1 36

The Error Log

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

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

The data in the error log is gathered primarily for return to SafeNet to assist with troubleshooting.

Recovering the error log

The recommended method for retrieving the error log from a TCP/IP or Async HSM is to use the SafeNet error log retrieval program (lrp.exe) that makes use of the functions documented in this section. This program is distributed separately.

To use the error log retrieval program it must first be installed on a PC. The HSM is then taken off line and connected to the PC which then acts as the host. The retrieval program can then be run and the errorlog details displayed using the program’s user friendly interface.

(41)

HSM_STATUS

PHW

D

SHP

D

PSO/PSG

D

SHP Toolkit MK2

D

Card Issuance (SHP Toolkit

EMV)

D

Attribute Description Request Content Length

01 1 h Function Code

Attribute Description Response Content Length

01 1 h Function Code

rc 1 h Return Code

RAM Status 1 h ROM Status 1 h DES Status 1 h Host Port Status 1 h Battery Status 1 h Hard Disk Status 1 h RSA Accelerator 1 h Performance Level 1 h Reset Count 2 h Calls in last minute 4 h Calls in last 10 mins. 4 h Software ID length 1 h Software ID n h

This function activates the self-tests and returns the results to the host.

* RAM Status This is the result of performing a OS function to test the RAM. A failure indicates faulty RAM. 0 = passed and 1 = failed.

* ROM Status This is the result of performing a CRC check on the ROM. A failure indicates ROM corruption or tampering. 0 = passed and 1 = failed.

DES Status 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.

Host Port Status This is the result of performing various status checks to ensure the host port can be configured and perform successful communication. Failure may indicate either a software or hardware problem. 0 = passed, 1 = failed, and 02 = passed but not connected (for Ports).

Note: The return value (02) is valid for SHP platform only.

Battery Status 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. * Hard Disk

Status

Read IDE status port to ensure no IDE errors are reported. 0 = passed and 1 = failed.

RSA Accelerator 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. Performance

Level

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.

Reset Count Number of time the HSM has been reset since manufacture. The value is returned with least significant byte first

(42)

Calls in last minute

Number of function calls to the host made in the last minute. The value is returned with least significant byte first.

Calls in last 10 mins

Number of function calls to the host made in the last 10 minutes. The value is returned with least significant byte first.

Software ID length

The number of bytes (characters) making up the Software ID. The maximum is 8.

Software ID 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.

ESMID Part of the SHP Toolkit MK2 function call. The ESMID is a pointer to a NULL terminated string that identifies the name of the SafeNet HSM (ESM) to which functions are directed. The SafeNet HSM name is set using the

wincommsconfig utility provided as part of the SHP Toolkit product suite. * The values of fields RAM, ROM and Hard Disk status are not valid for the SHP platform, and hence a default value (0) is returned for these items.

SHP Toolkit MK2

int EFT_01_GetESMStatus (

IN UCHAR *ESMID,

OUT UCHAR *RAMStatus, OUT UCHAR *ROMStatus, OUT UCHAR *DESStatus, OUT UCHAR *HostPortStatus, OUT UCHAR *BatteryStatus, OUT UCHAR *HardDiskStatus, OUT UCHAR *RSAAccelerator, OUT UCHAR *PerformanceLevel,

OUT USHORT *ResetCount,

OUT ULONG *CallsInLastMinute, OUT ULONG *CallsInLast10Minutes,