You don’t need to buy a HSM to see how it works

Hi everyone,
In my previous blog I told you that my next set of blogs will be on building a Java application to provide basic cryptographic functionalities using a HSM. So, this is the first part of it. Before building the application, we need configure a HSM simulator. Through this blog I’m going to show you how to configure, Utimaco Cryptoserver Simulator and PKCS #11 API on your development environment.

FYI : It is required to have a basic understanding on PKCS #11 before reading this blog. You can refer to my previous blog on PKCS #11 if you need.

So, I am going to discuss this under three sections. First section will be on setting up the simulator and administration tool. Second section is all about configuring PKCS #11 to use the simulator. Initiating a token and a PIN for a PKCS #11 slot using P11CAT(PKCS #11 CryptoServer Administration Tool) will be discussed in section 3.

So let’s roll…

1. Setting up the simulator and administration tool

1. First you need to download Utimaco Cryptoserver Simulator from here.
   FYI : You need to register in Utimaco portal before downloading the simulator. Sometimes it may take a while to get your account confirmation. I faced a problem when choosing a password for portal, so keep in mind choose a password containing only upper case letters, lower case letters, digits, and any from following set of special character: $ — / : — ? { ~ ! “ ^ _ ` [ ]
2. Extract the downloaded .zip file.
3. Open CryptoServer_Manual_Systemadministrators.pdf in <Extracted_Folder>/Documentation/Administration Guides/
4. First go through section 3.1 in the pdf and make sure you have met the system requirements for installation.
5. For Windows installation go through section 3.3–3.3.2
   For Linux installation go through section 3.4–3.4.3
   (ie. Required instructions for setting up the simulator and administration tool are provided in above sections.)
6. If you followed the given instructions properly now you have running a simulator and CAT(Cryptoserver Administration Tools). Following is a simple test to make sure your simulator is running.
   1. First run the simulator. (Instructions provided in installation sections mentioned above.)
   2. Then start CAT. (Instructions provided in installation sections mentioned above.)
   3. Click on Devices button(In top left corner) in CAT and a window will pop-up.
   4. Type 3001@localhost on New Device text field and press on Add to List.
   5. Now device will appear on Device List and select device from the list and click on Test button. If simulator is working properly a message will pop-up showing ‘Specified CryptoServer (3001@localhost) connected’.

CAT before testing the device.

I hope now you have successfully installed the simulator and administration tool on your development environment. If not please again go through installation sections and see if you have done the configurations properly.

2. Configuring PKCS #11

1. First you need to generate a MBK(Master Backup Key) using CAT. (Refer to section 4.8 in above PDF; For login to the device ADMIN.key file can be found in <Extracted_Folder>/Software/<Your_OS>/<System_Architecure>/Administration/key/)
2. Then you have to create a file called cs_pkcs11_R2.cfg which is the configuration file containing required configurations of PKCS #11 module. For now you can use the sample provided in <Extracted_Folder>/Software/Linux/x86–64/Crypto_APIs/PKCS11_R2/sample)
3. Open configuration file and do the following changes;
   Comment all lines of [CryptoServer] sections with their configurations except one [CryptoServer] section and set it’s device parameter to 3001@localhost.
   FYI : For more information on configuration parameters refer to section 4 in CryptoServer_PKCS11_R2_DevGuide.pdf in <Extracted_Folder>/Documentation/Crypto_APIs/PKCS11_R2 folder.
4. Copy the created configuration file to safe location and add an environment variable CS_PKCS11_R2_CFG pointing to location of the configuration file.
   To add the environment variable,
   Windows users;
   Enter following command in command line.
   set CS_PKCS11_R2_CFG=”PathToConfigurationFile”
   Linux users;
   Add following line to top of .bashrc in user_home.
   export CS_PKCS11_R2_CFG=PathToConfigurationFile
5. Check the variables have been initialized successfully by running following command.
   Windows users;
   echo %CS_PKCS11_R2_CFG%
   Linux Users;
   echo $CS_PKCS11_R2_CFG
6. Then you need to copy the PKCS #11 Module(.so/.dll) file to somewhere safe. (You can find the PKCS #11 Module in <CryptoServer_Extracted_Folder>/Software/<Your_OS>/<Sys_Arch>/Crypto_APIs/PKCS11_R2/lib folder)

Now you have successfully configured PKCS #11 in your development environment.

FYI : Following steps are same for any HSM that supports PKCS #11 except step 1. There will be changes in the names of the configuration parameters and environment variables, but overall configuration is same as above.

Let’s see how to use P11CAT provided by Utimaco to view and use the HSM.

3. Initiate a token and PIN for a slot using P11CAT

P11CAT is a dedicated PKCS #11 administration tool use configure PKCS #11 slots of the device. So we know that each slot has a Admin user, Security Officer(SO) and a User(ie. PKCS #11 Specification). P11CAT can be used to create and manage users in each slot. Also P11CAT can be used to generate or import secret keys, key pairs.

So let’s get started…

Hope you already completed the section 1 and 2 successfully. It is a prerequisite for this section.

First run P11CAT.
Go to <Extracted_Folder>/Software/<Your_OS>/<System_Architecture>/Administration/
Run following command in terminal/command line. (FYI: Better to run as super user in Linux)
java -jar p11cat.jar

Main interface of P11CAT

Then you need to initiate a token and pin for a slot. Steps are as follows,
1. Select a slot from slot list and click on Login/Logout button. Select Login Generic and provide, username as ‘ ADMIN’ and ADMIN.key file which is used earlier to login.
2. Click on Slot Management button and select Init Token. Provide a PIN for SO(Security Officer)and click on Init Token button.
3. Again go to Login/Logout section and click on Logout All button and select Login SO and enter the PIN you provided earlier.
4. Then again go to Slot Management and select Init PIN. Provide a PIN for User and click on Init PIN.
5. Again logout from all and login as user.
Now you have successfully initiated a token and a PIN for a slot. So you can use that slot to carryout cryptographic operations.

Following is a simple example of generating a pair of RSA keys using P11CAT.

I believe that now you have successfully logged in as User for the selected slot. Here’s how you do it,
1. Click on Object Management button.

Object Management interface

2. Click on Generate button under Object Management section.
3. Select Generate Key Pair and select RSA as mechanism.
4. Click on Generate.

Object Management Interface after successful RSA key pair generation

Now you should be able to see the generated pair of keys. This will also guarantee that you have successfully completed all three main steps.

For more information on P11CAT refer to CryptoServer_Manual_P11CAT.pdf in /Documentation/Administration Guides.

I hope you got everything correct. If any doubts put it in responses section. So that’s it for today. In my next blog I’ll show you how to build a simple Java application which encrypt and decrypt a given text, using a HSM.

Thank you very much!!! Don’t forget to comment on things that I need to improve.

Cheers!!!