Documentation
- Installation
- Usage
- HTTP GET Interface and terminology used
- Key Generation
- Key Generation from components
- Key Check Value Calculation
- DES Encryption/Decryption
- Key Translation
- MAC Generation
- PINBLOCK Generation
- CVV Calculation
- PVV Calculation
To Install simply unzip the zip file, and you should see the following Directory structure
- Keys
- Library
- Log
- properties
- webapp
HSM.jar
To Start the application simply type
java -jar HSM.jar
After the application is started two services will be available. The webmenu service at default port 8080 for testing and general server administration and the http interface at port 9090.
To login to the webmenu, default username and password is admin and password 12345
Below is the application menu screenshot
All the configurable properties are in the properties directory, which should be self explanatory.
The LMK(Lokal Master Keys) are stored in the keys folder. The DES LM is in the file DES.key while the 2TDES and TDES LMK are in the file DESede.key
All the logs are stored in the log directory.
The HTTP Interface is located at the default port 9090, its a simple HTTP GET based interface which allows to be easily used programatically from other applications. For example to generate a key just type the following url
http://hsmhostt:9090/genKey?alg=DES&keyType=CLEAR
And the output will be 3E04CB5789B60E75;653C0B
First some terminology definitions
keyType means the type of key used or generated which can be a CLEAR KEY or a CRYPT ed key. A Clear key is the key in plain text HEXSTRING. a CRYPT ed is a key that is wrapped/encrypted under another key, in HarSM that usually means the LMK.
dataType is the format of the data used, which can be a HEXSTRING or an ASCII Text
For example the ASCII Text SIMPLEHSM
Has the HEXSTRING Value of 53494D504C4548534D which is the ASCII Byte HEx value of the String.
For some functions such as the MAC and encryption/decryption routine, HarSM accept the input to be either of ASCII Text or HEXSTRING.
KCV means the key check value of the key
HarSM can generate DES, TDES and 2TDES key.
FORMAT :
http://hsmhost:9090/genKey?alg=[DES/TDES/2TDES]&
keyType=[CLEAR/CRYPT]
OUTPUT :
KEY;KCV
EXAMPLE :
http://localhost:9090/genKey?alg=DES&keyType=CLEAR
RESULT
3E04CB5789B60E75;653C0B
5. Generate Key from Components
This method is for key generation from preset components using the XOR Method.
FORMAT:
http://hsmhost:9090/genKeyCmp?cmps={KeyComponent1;KeyComponent2;xxxxx}
&keyType=[CLEAR/CRYPT]&alg=[DES/TDES/2TDES]
OUTPUT :
KEY;KCV
EXAMPLE :
http://localhost:9090/genKeyCmp?cmps=5876B6E561317C73;
B02F8A8AB0853473&keyType=CLEAR&alg=DES
RESULT :
E8593C6FD1B44810;859B84
Calculates the key check value of the key. Don't forget to specify wether its a CLEAR key or CRYPT key(encrypted under the HarSM default LMK)
FORMAT :
http://hsmhost:9090/checkKey?alg=[DES/TDES/2TDES]&
keyType=[CLEAR/CRYPT]&key={Key}
OUTPUT :
KCV
EXAMPLE
http://localhost:9090/checkKey?keyType=CLEAR&alg=DES
&key=AD9440438571016B
RESULT
696A9C
If Key=Null LMK is USed
FORMAT :
http://hsmhost:9090/crypt?data={DATA}&dataType=[HEXSTRING/ASCII]
&key={KEY}&keyType=[CLEAR/CRYPT]&function=[ENC/DEC]
&alg=[DES/TDES/2TDES]&outputTye=[ASCII/HEXSTRING]
OUTPUT : PROCESSED DATA
EXAMPLE 1 :http://localhost:9090/crypt?data=0100000000000000&function=ENC&alg=DES
&dataType=HEXSTRING&key=BC2092F2B6AE2AD0&keyType=CLEAR
&outputType=HEXSTRING
RESULT :
B146671A31DD7D4F
EXAMPLE 2 :
http://localhost:9090/crypt?data=B146671A31DD7D4F&function=DEC&alg=DES
&dataType=HEXSTRING&key=BC2092F2B6AE2AD0&keyType=CLEAR
&outputType=HEXSTRING
RESULT :
0100000000000000
To Translate a key from under one key to another key
If key2 value is null LMK is used
FORMAT :
http://localhost:9090/trans?data={source key}&key={Wrapping Key}&keyType=[CLEAR/CRYPT]&key2={target wrapping key}&keyType2=[CLEAR/CRYPT]
OUTPUT :
KEY;KCV
EXAMPLE : http://localhost:9090/trans?data=23C0F94353687655&key=4767355BDFCD4ED7
&keyType=CRYPT&alg=DES&key2=2AA20D8AE9BC5440&keyType2=CLEAR
RESULT :
19DF9AD52A069C4A;60EB6B
This function generates a standard ANSI MAC based on CBC DES algorithm
Which is the most commonly used MAC in ISO 8583.
FORMAT :
http://localhost:9090/genMAC?data={Data to be MACed}
&dataType=[ASCII/HEXSTRING]&key={MACKEY}&keyType={CLEAR/CRYPT}
&outputType=[ASCII/HEXSTRING]
OUTPUT :
MAC
Example http://localhost:9090/genMAC?data=03082040172040171&key=443BB859A146CB8C
&keyType=CRYPT&dataType=ASCII&alg=DES
RESULT :
1B4F838C
This function generates an encrypted pinblock according to the ANSI ISO-0 Format. Which again is the most commonly used format for PINBLOCK.
FORMAT :
http://hsmhost:9090/pinblock?pin={PIN}&pan={FULL PAN}&key={ZPK KEY}&keyType=[CLEAR/CRYPT]&alg=[DES/TDES/2TDES]
EXAMPLE :http://localhost:9090/pinblock?pin=222222&pan=5104813099990418
&key=19DF9AD52A069C4A&keyType=CRYPT&alg=DES
RESULT :
FCB4BC06025448B9
This function calculate the CVV for a PAN. Compatible with VISA, Mastercard and AMEX CVV/CSC.
Notes :
- For CVV2 use SVC 000
- For CVV3 SVC is 502
- iCVV use svc of 999
FORMAT :
http://hsmhost:9090/cvv?&pan={FULL PAN}&cvkpair={CVK Key Pair }&svc={Service Code}&expdate={Expiry Date in mmYY or YYmm format}
EXAMPLE :http://localhost:9090/cvv?pan=123456789012345&
cvkpair=12345678123456781234567812345678&svc=233&expdate=1105
RESULT :
242
UPDATE, MAKE SURE YOU KNOW WHICH PART OF THE PAN TO USE FOR THIS
ITS USUALLY THE RIGHTMOST 11 DIGIT EXCLUDING THE LAST DIGIT AND THE CHECK DIGIT.
Calculates the PVV value for a given PIN and PAN number. Compatible with VISA and Mastercard PVV algorithm.
FORMAT :
http://hsmhost:9090/pvv?&pan={FULL PAN}&pvkpair={PVK Key Pair }&PVKI={PVK Index Value}&pin={CLEAR PIN}
EXAMPLE :http://localhost:9090/pvv?pan=5999997890123412&pin=1234
&pvki=1&pvkpair=4CA2161637D0133E5E151AEA45DA2A12
RESULT :
0798