Want to know how to talk to a HSM at code level?

Hi friend 😙,
Here you’re to read the second part of my story. In the first part I explained you how to configure a HSM simulator and PKCS #11 API. Through this post I’m going explain you how to build a simple Java application to use HSM to encrypt and decrypt a given sample text.

Note : In the post I’ll be providing only code blocks related to cryptographic operations (encryption, decryption, key gen. etc.). You can find the complete source code of a sample application in the link provided below.

Before starting to build the application, there are two questions that needs to be answered.

HSM vendors provide the PKCS #11 implementation in C language. Hope you already know it, then here is an obvious question…

How to develop a Java application using C module?

So we need a wrapper to map C data structures to Java data structures and vice versa. Some of famous wrappers are SunPKCS11, IBM PKCS11 and IAIK PKCS11 wrapper. SunPKCS11 doesn’t provide an object oriented mapping of data structures and IBM wrapper isn’t an open source project. So for this application I’m going to use IAIK PKCS #11 wrapper.

Why IAIK PKCS #11 Java wrapper?

It is a open source wrapper with an object oriented realization of PKCS #11 API specification. This provides an interface for JAVA applications to access PKCS #11 module(.so/.dll) functionalities. For more information regarding the wrapper visit IAIK API documentation.

So, here’s the best part… Coding!!! 😃 😃

Note : Throughout the tutorial I’ll be using Intellij IDEA as IDE. If you’re using another IDE that is totally fine.

First we need to build a maven project. Hope you know how to build a maven project. If not this is the way for Intellij.

Here’s how you add IAIK wrapper to your project.

Note : 4th and 5th steps are explained for Intellij IDEA. If you’re using another IDE see how to add .jar file dependency in your IDE.

1. Download IAIK PKCS #11 wrapper from here. (Note : You need to register in IAIK to download the wrapper.)
2. Extract the downloaded .zip file.
3. Open created project.
4. Go to File > Project Structure > Modules > Dependencies
5. Select + mark on right and select Jars or Directories and point to iaikPkcs11Wrapper.jar.(You can find the iaikPkcs11Wrapper.jar inside the bin folder of extracted folder.)

Now you’ve successfully added the IAIK PKCS #11 wrapper support for your application. 😃 😃 😃

Before continuing further more you need to have already completed three sections discussed in my previous blog ☺️

Then you know how to start the simulator. So, start the simulator.
Also I hope you have already configured a slot in the simulator and remember the User PIN 😜

So, here’s how this works,
Before carrying out any cryptographic operation using the HSM you need to instantiate a session with a token.

Here’s how to initiate session;

Initiate a session with the device

I have commented on each line so that you can understand what is happening in each line.

From here onward, I’ll be discussing how to encrypt and decrypt a text using a symmetric key.

Before encrypting/decrypting a cipher text you need to generate a key. Let’s see how to generate an AES(Advanced Encryption Standard) key.

Following code block goes to ‘//Perform your cryptographic operation here’ in above code.

Sample code for generating AES key using the HSM

FYI : Above scenario is same for any symmetric key generation. You can change the parameters as you want. When it comes to generating asymmetric keys, you should create templates for both public key and private key. Also for more information different key generation mechanisms, refer to PKCS #11 Mechanism Specification.

So now you’ve successfully generated a AES key. You can view the generated key using P11CAT(ie. Tool discussed in last part of my previous blog.).

Let’s see how to encrypt a given text using the generated AES key.

Encrypt a given text using generated AES key

This code block goes after the key generation code block. In here I’ve used CBC(Cipher Block Chain) padding mode to encrypt the text. Refer PKCS #11 Mechanism Specification for more information on available encrypting mechanisms.

Also you should know that the above scenario is same for any data encryption scenario. Only the key and the mechanism changes.

FYI : Mechanisms have constraints such as input size, block size, mechanism parameters etc. It is essential to refer PKCS #11 Mechanism Specification before using a mechanism.

Now you know how to encrypt a given text. Here’s how to decrypt a ciphered text.

Decipher a encrypted text

This code block goes after encryption code block and I have used the encrypted data for decryption. So you should be able to get the decrypted text, as same as the text used for encryption, printed in the console.

FYI : Mechanisms used in decryption are same as the encryption mechanisms. Also mechanism parameters stay same as encryption.

Now you have successfully encrypted and decrypted a given text using a generated key.

I hope now you’ve some idea on how things work at code level. So, this it for today. I’ll be back with some example codes on signing/verification and hashing operations carried out using a HSM. This is the link to Github repository of a sample application developed by me, for key generation and encryption/decryption operations. You can use it to play with the simulator and understand.

Please be kind enough to ask in response section for any clarifications.

Thank you for being with me for this long. 😙 😙

Stay tuned!

Happy reading!!!

Cheers!!!