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
