Clear PIN User Guide

Preface

Preface
2012 SafeNet, Inc. All rights reserved.
Part Number: 007-012067-001 (Rev A, 06/2012)
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
Revision
A

SafeNet, Inc.

Software ID
M090600E

Action/Change
Initialrelease.

Date
June 2012

Clear PIN User Guide

Preface

Technical Support
If you have questions or need additional assistance, please contact Technical Support using this
information:
Customer Connection Center (C3)
http://c3.safenet-inc.com

Existing customers with a Customer Connection Center account can log in to manage incidents,
get latest software upgrades and access the complete SafeNet Knowledge Base repository.
Supports and Downloads
http://www.safenet-inc.com/Support

Provides access to knowledge base and quick downloads for various products.
E-mail based support
support@safenet-inc.com

Telephone-based support

ii

United States

(800) 545-6608, (410) 931-7520

France

0825 341000

Germany

01803 7246269

United Kingdom

01276 608000, +1 410 931-7520

Australia and New Zealand

1 410 931-7520 (Intl)

China

(86) 10 5781 0666

India

+1 410 931-7520 (Intl)

SafeNet, Inc.

Clear PIN User Guide

Table of Contents

Table of Contents
Preface................................................................................................................................................. i
Technical Support ............................................................................................................................. ii
Chapter 1 Introduction..................................................................................................................... 1
Overview ....................................................................................................................................................................... 1
Common Terms and Phraseology .................................................................................................................................. 1
Supplemental Documentation ........................................................................................................................................ 1
Console operations support............................................................................................................................................ 1
Host functions support ................................................................................................................................................... 2

Chapter 2 Host Functions ................................................................................................................ 3

Overview ....................................................................................................................................................................... 3
Function Message Formats ............................................................................................................................................ 3
Function Descriptions .................................................................................................................................................... 4

CLR-PIN-ENCRYPT .................................................................................................................... 4
Appendix A Error Codes ................................................................................................................. 7
Function Error Codes..................................................................................................................................................... 7

SafeNet, Inc.

iii

Clear PIN User Guide

iv

Table of Contents

SafeNet, Inc.

Clear PIN User Guide

Chapter 1
Introduction

Chapter 1
Introduction
Overview
This document defines the extended Clear PIN option functionality for the software
operating on a MarkII HSM.
This functionality is an optional extension to the standard SafeNet HSM functionality.
Please refer to the Mark II Console User Guide, and the Mark II Programmers
Guide, for details of the standard functionality.
The Clear PIN option functionality incorporates HSM Console Operations and Host
Functions.
Note: To enable Clear PIN option functionality, please contact Safenet Technical
Support.

Common Terms and Phraseology

This or other documentation may refer to a SafeNet HSM security module as ESM,
ESM2000, PHeft, HSM or Safenet HSM Payment. The device has been renamed as
SafeNet Luna EFT (PH-EFT) and is referred to as Luna EFT, hereafter. The names
ESM, ESM2000, PHeft, HSM, SafeNet HSM Payment (SHP), and SafeNet Luna EFT
(PH-EFT) all refer to the same device in the context of this Guide.

Supplemental Documentation
This functionality is an optional extension to the standard Mark II functionality.
Please refer to the following documentation for details of standard Mark II
functionality.

Luna EFT (PH-EFT) Installation Guide

Luna EFT (PH-EFT) Communications Guide Mark II Edition

Luna EFT (PH-EFT) Programmers Guide Mark II Edition

Luna EFT (PH-EFT) Console User Guide Mark II Edition

Console operations support

The console operation supported by the Clear PIN Options functionality is as follows:

SafeNet, Inc.

Enabling or disabling of the Clear PIN translate host function.

Clear PIN User Guide

Chapter 1
Introduction

Host functions support

The host functions include options to support:

The encryption of a clear PIN.

Translation of a PIN from encryption under a PPK to encryption under another

PPK.

The decryption of a PIN from encryption under a PPK to yield a clear PIN.

SafeNet, Inc.

Clear PIN User Guide

Chapter 2
Host Functions

Chapter 2
Host Functions
Overview
This chapter details the extended formats and host functions supported by the Luna EFT for
the PIN customization. For the standard Mark II functionality please refer to the Mark II
Programmers Guide.

Function Message Formats

Data Item Representation in Request/Response Messages
Request and response content may use the following operators and qualifying letters.
Operator

Meaning

Decrypt in Electronic Code Book (ECB) mode.

Encrypt in Electronic Code Book (ECB) mode.

Qualifier

Meaning

The left part of a Key Pair

The right part of a Key Pair

Used for receiving

Used for sending

Variant

Prefix to indicate a key pair.

Each field has an associated attribute and its length in bytes. The attributes are defined as follows:
Attribute
B
H
D
X
B64
B512
P-key

SafeNet, Inc.

Description
Represents a binary digit. These are always in multiples
of 8.
Represents a hexadecimal digit. These are always
grouped in pairs.
Represents a BCD digit. These are always in pairs.
Represents a binary byte.
Represents a 64 bit field.
Represents a 512 bit field.
Represents an RSA public key.

Clear PIN User Guide

Chapter 2
Host Functions

Function Descriptions
CLR-PIN-ENCRYPT
Request Content
EE0600

FM
PIN-Len
PIN
ANB
PPK-Spec

Response Content
EE0600
Rc
ePPK(PIN)

Lengt
h
3
1

Attribute

1
Var
6
Var

h
d
d
K-Spec

Lengt
h
3
1

Attribute
h
h

Function Code
Return Code

Encrypted output PIN

h
h

Description
Function Code
Function Modifier = 00
Number of digits in PIN field
Clear PIN
Account Number Block
Key specifier for PPK
(Formats: 0 - 3, 10, 11, 13, 12,
14, 17, 18, 20, 90)
Description

This function accepts a clear PIN, formats it into an ANSI PIN Block and encrypts the Block
using the supplied PPK.
FM

= 00. Must be set to zero.

PIN-Len

Identifies the number of digits in the PIN, in the range 4 12.

PIN

Clear PIN consisting of from 4 to 12 digits, packed 2 digits per byte.

If PIN-len is odd, the digits must be left justified in the PIN field
with one trailing decimal pad digit.

PPK-Spec

Key specifier for the PPK (eKMv1 - Format 0-3, 10, 11, 12, 13, 14,
20 or 90).

ANB

12 PAN digits of the Account Number Block used to format the

ANSI PIN Block.

NOTES
Please contact SafeNet if you require this functionality or further details.
PTK-EFT

int EFT_EE0600_ClearPinEncrypt(

IN

UCHAR

FM,

IN

UCHAR

PinLen,

SafeNet, Inc

Clear PIN User Guide

SafeNet, Inc.

Chapter 2
Host Functions

IN

EFTBUFFER *PIN,

IN

UCHAR

ANB[6],

IN

KEYSPEC

*PPK,

OUT

UCHAR

ePPK_PIN[8]);

Clear PIN User Guide

Chapter 2
Host Functions

SafeNet, Inc

Clear PIN Option User Guide

Appendix A
Error Codes

Appendix A
Error Codes
Please refer to the SafeNet HSM Communications Guide for other host-connection-specific error
codes.

Function Error Codes

Error Code

Meaning

00

No error

01

DES Fault (system disabled)

02

Illegal Function Code

PIN MAILING not enabled

03

Incorrect message length

04

Invalid data in message: Character not in range (0-9, A-F).

05

Invalid key index: Index not defined or key with this Index not stored.

06

Invalid PIN format specifier:

only AS/ANSI = 1 & PIN/PAD = 3 specified.

07

PIN format error: PIN does not comply with the AS2805.3 specification, is in an
invalid PIN/PAD format, or is in an invalid Docutel format

08

Verification failure

09

Contents of key memory destroyed: e.g. the Eracom Security Module was tampered
or all KEYs deleted.

0A

Uninitialised key accessed:

Key or Decimalization Table (DT) is not stored in the Eracom Security Module.

0B

Checklen error: customer PIN length is less than the minimum PVK length or less
than Checklen in function.

SafeNet, Inc.

Clear PIN User Guide

Appendix A
Error Codes

SafeNet, Inc.