Sample: pinenc:

Demonstrates how custom functionality can be implemented. The only use of the external Cryptoki interface is to login the operator.

The FM provides a simple pin encryption facility. User pins that are encrypted under a RSA public key (perhaps in a Web Browser) can be sent to the HSM to be re-encrypted under a Symmetric Pin Encryption key.

pinenc has code samples for the following functionality:

>Registering a message handler

>Parsing request messages and switching between different command codes

>Using the internal Cryptoki implementation to get services from the Luna Core.

>Using CT_SetPrivilegeLevel to override Cryptoki rules

>Using FMCE API to get raw AES and RSA crypto services

>Using the SMFS to store sensitive keys.

>Generating Debug trace messages

>Generating Secure Audit entries

>Constructing and returning a response message

The FM implements four custom commands:

PE_CMD_GEN_KEYS:

Description:

Generates an RSA key pair and an AES key and stores them in the SMFS

NOTE   The FM opens a cryptoki session inside the HSM and relies on that session having the same login status as the client process calling the custom command.

Input:

zone, slot_num

Output:

status

Process:
C_OpenSession, 
C_GenerateKeyPair( 2048 bit RSA key )
CT_SetPrivilegeLevel(1)
C_GetAttributeValue to Read private key attribute
C_Finalize
AES key = FM_GetNDRandom
If cannot open SmFs file then Create SmFs file.
Store RSA and AES key into SmFs file
FM_AddToExt( audit entry ) 
Return status

PE_CMD_GET_PUBKEY:

Description:

Returns the previously generated RSA public key

Input:

zone

Output:

status, encoded pubkey

Process:
If ( pub key is not in cache ) open and read SmFs file into cache
Encode rsa pubkey for response
Return status, encoded pubkey

PE_CMD_CLR_PIN_ENCRYPT:

Description:

Uses stored RSA public key to encrypt a clear pin block

Input:

zone, clear pinblock

Output:

status, encrypted pinblock

Process:
If ( pub key is not in cache ) open and read SmFs file into cache
Use FMCE Api to OAEP encrypt the pinblock
Return status, encrypted pinblock

PE_CMD_TRANSLATE_PIN:

Description:

Re-encrypts the pinblock from RSA to AES

Input:

zone, encrypted pinblock

Output:

status, encrypted pinblock

Process:
If ( pri key is not in cache ) open and read SmFs file into cache
Use FMCE Api and RSA pri to OAEP decrypt the pinblock
Use FMCE Api and AES key to ECB encrypt the pinblock
Return status, encrypted pinblock

pinenc Test Application

pinenctest [-z<zone#>] [-s<slot> –p<pin> gen ] | [-d<hsm> test ]
-z<key zone number>   Use key zone # - (default 1).e.g. -z123
-s<slot number>   Use slot # - (default 1) e.g. -s3
-d<device number>   Use HSM device # - (default 3) e.g. -d3
-p<pin> Use pin to log into slot
gen Perform key generate operation
test Perform pin translate tests (default)
Description:

The pinencetest application is used to exercise the pinenc sample FM. The FM operates in two modes. Either it is generating a key set or it is using a key set. The pinenctest application allows the user to specify whether to generate a key set (gen) or to test a key set (test).

When generating a key set, you must determine the Cryptoki slot number on which you want to login and generate a key set. The Test application requires a Cryptoki token to generate key sets. So when you ask the FM to generate keys it needs to know which slot number to use. The test mode uses the keys already generated and requires you to specify only the device number. In order to handle multiple HSM instances you must specify which HSM is to be used for the test. The device number specifies the HSM instance.

To access the slot number and determine if the HSM supports FMs:

1.Launch lunacm and execute the command slot list

slot list

2.Record the slot number for the device.

3.Exit lunacm.

4.For Luna PCIe HSM, use ctfm q command to list available FM-capable HSMs.
For Luna Network HSM, use hsm fm status command.

Process:
C_Initialize, Find Admin Token, C_OpenSession, C_Login(Admin Password)
C_GenerateKeyPair( 2048 bit RSA key )
CT_SetPrivilegeLevel(1)
C_GetAttributeValue to Read private key attribute
C_Finalize
AES key = FM_GetNDRandom
If cannot open SmFs file then Create SmFs file.
Store RSA and AES key into SmFs file
FM_AddToExt( audit entry )
Return status