HThalesAdaptor v 0.1

Java Thales Host Security Module (HSM) Library

for Payment Systems and bank Interchange message

PINBLOCK, MAC, CVV, PVV, ZPK, TPK, TAK, LMK

 

MENU

• HThalesAdaptor

 

• Documentation

 

• About Me

 

 

Documentation

1. Installation
2. Core Components
3. Usage
   1. Normal Usage
   2. HThalesMSg XML definition
4. Q2/JPOSEE Usage
5. PCI Compliance
6. Adaptation for QMUX
7. Throughput and Multiple Connections

1. Installation

You can download the precompiled JAR file or the source file,

If you don't wanna go to the trouble of compiling it, just copy

HThales.jar somewhere in your classpath directory.

For Q2/JPOS-EE usage I Think on most of the cases you need to copy the jar file into the lib directory inside the deploy folder(the one where all your Q2 bean xml definition resides.

UPDATE : JPOS Q2 uses a seperate classloader for loading jars in deploy/lib directory.

Unfortunately, my HThalesAdaptor.class uses instanceof Operator, so it won't work for Q2 unless you compile the source along with the JPOS module and its all in one jpos-ee.jar

 

And don't forget to copy your Message Definition XML files, to a directory somewhere.

2. Core Components

HThalesMsg

This is the FSDMsg style Thales Racal command parser, with a few added field type and seperator compared to the original FSDMsg, they are

Field Type : T

Represents a Thales KeyScheme+Key

Length : 16H, 1A+16H/32H/48H

Supports the keySchemes

• None/Z
  Encryption of a single length DES key using ANSI X9.17 methods. Used for encryption of keys under a variant LMK, and can also be used for the import or export of keys.
• U
  Encryption of a double length DES key using the variant method; used for encryption of keys under a variant LMK.
  
• T
  Encryption of a triple length DES key using the variant method; used for encryption of keys under a variant LMK.
  
• X
  Encryption of a double length key using ANSI X9.17 methods; only available for import and export of keys. This mode is enabled within the Configure Security command.
  
• Y
  Encryption of a triple length key using ANSI X9.17 methods; only available for import and export of keys. This mode is enabled within the Configure Security command.

the field type T will set lenght to the default lenght specified in the schema definition, until it recieves a keyscheme that overrides it.

So practically speaking for ZMK keys you use field definitions like

<field id='zmk' type='T' length='16'/>

When theres no prefix in front, it assumes a 8 byte, 16 HEXCHAR key

With specific prefix U,T,X,Y it will automatically select the correct lenght.

And this is for CVK, since the default is usually 32
<field id='cvk' type='T' length='32'/>

 

PS, Adding additional keyscheme for EMV and etc is trivial if you're willing to look at the source

 

 

Field Type O

For optional data, that may or may not be present, usually used in conjuction with pre separators

 

Seperator ES

Gives you a semicolon ';' as a separator

 

PreSeparators

Just like a separator, but their placed at the start of the field, usually used with optional data.

PreSeparator SS = ';'

PreSeparator SP = '%'

PreSeparator SC = 'X'19'

 

 

 

 

HThalesCore

Reponsible for creating the request, by looking up the schema definition files in the specified directory and creating connection

 

HThalesAdaptor

A Q2ChannelAdaptor like component that if you use a JPOS Q2 architecture will take care of keeping the connection alive and uses Java Spaces.

 

 

 

 

3. Usage

For normal usage, use code like

 

I've implemented some HSM commands in the HThalesCore as a reference guide, when you're creating your own commands with definition files your code will probably look like

Thales JC message for PINBLOCK

With message definition like

File : hsm-JC.xml

 

And the corresponding response definition

File : hsm-resp-JD.xml

So .....

When you need to implement a new command, just prepare the FSD defintion file.

Here is another example that makes use of the optional data field and preseparators

File : hsm-DW.xml

 

File : hsm-DX.xml

With code like

 

 

Thread Safety and Concurency

Unlike ISO8583 switching host that sometimes route messages to other far flung host, and messages response can arrive in different order;

I'm pretty sure that Thales HSM RG series process incoming messages synchroniously FIFO(First In First Out),

Just add a synchronized keyword/block in your code, and it should be fine.

 

Variable Length Field

When dealing with variable lenght fields, just browse the schema definition example so that you can implement the proper one for your needs.

 

 

 

4. Q2/JPOS EE Usage

For Q2 we have the HThalesAdaptor Q2 Bean, with xml deployment like this

You cand send message like

Or to ensure thread safety wrap it under TSpace

The HThalesAdaptor accepts both FSDMsg and TSpace input into its in space.

JMX is supported, so you can manage it via the JMX console for some cool stuff.

5. PCI Compliance

I think HThalesAdaptor should be PCI compliant.

The thing is, last time I checked TSpace and JPOS default space implementation doesn't serialize to disk. I don't know if that has changed.

Why does this matter ?, because PCI forbid any sensitive info stored in permanant media.

If it does, you need to wrap your request to other Java space implementation

6. QMUX and Thales Racal Message Trailer

No, you can't currently wrap HThalesAdaptor in a Qmux, I don't see any hard requirements for it. However since a few of you in JPOS mailing list insist on using it, my tip is, just recast FSDMsg to FSDISOMsg, and send it over the wire.

Add FSDISOMsg handling to HThales adaptor space input, and don't forget

in your FSD XML definition every last field should use the FS type, so that JPOS will ad 1C after it, after that add in the field "11" and "41" which the QMux uses.

7. Throughput

Right, to get the max rated troughput on your Thales HSM you usually need to have multiple connections.

Luckily Java Space and JPOS Q2 provides a very straightforward way to do this.

Create 2 deployment descriptor for HThalesAdaptor with different name attribute, referencing to the same in/out space

 

 

And just send it through space.

 

Problem solved.

The Space will do the balancing automatically for you.

 

 

 

 

Copyright Hairi Abass 2011