FM Samples

There are three sample FMs provided with the Luna FM SDK package:

>Sample: skeleton

>Sample: pinenc:

>Sample: wrap-comp:

NOTE   Sample FMs are distributed with the Luna FM SDK package. They have a similar file layout.

Each of the FM samples is structured in a similar way. Each sample directory contains:

makefile makefile to build host and HSM side code
fm directory holding HSM side source
host directory holding host (server) side source
include optional directory to hold common header files

Within the FM directory are files like these:

hdr.c header file for the production build of the FM binary image
sample.c HSM side; main source for FM
makefile Makefile to build the FM and the application

Within the host directory are files like this:

stub_sample.c host side stub (request encoder/decoder) (needed only for custom API)
sample.c main source for host side test application
makefile Makefile to build the host side application for emulation, or production

The samples are built using gnu make and the provided Makefiles. When working on a platform that has a native gnu make, such as Linux, you can use the system make command.  (For Windows, consider nmake.)

>Production build, no debug information in binaries:
make

>Production build, with debug information in binaries and optimization turned off:
make DEBUG=1

Binary files generated by the above variants are placed in different directories. The directory names used are:

obj-ppc FM Object files
bin-ppc FM Binary (FM image)

Host Binary files generated by the above variants are placed in different directories. The directory names used are:

output/obj Host side test application Object files
output/bin Host side test application executable

The binaries generated from each variant can be deleted using the target ‘clean’.

make DEBUG=1 clean

Signing FM Images

The build scripts generate the unsigned FM binary image when the HSM builds are performed. The binary images are named ‘<samplename>.bin’. Since these images are not signed yet, it is not possible to load them into the HSM. To use the key management scheme (using self-signed FM certificates), follow the steps listed below:

For PCIe HSM

1.Generate the key pair on a user partition/slot. Execute:

cmu generatekeypair -slot <slot> -password <userpin> -label <fmsign> -keytype <rsa> -sign <true> -verify <true> -modulusbits <2048>

This will generate a 2048 bit RSA key pair. The minimum key size for FM signing should be 2048 bits.

2.To make a self signed certificate, execute:

cmu selfsigncertificate -slot <slot> -password <userpin> -publichandle <pubkeyhd1> -privatehandle <prikeyhd1> -label <fmcert> -cn <fmcert>

3.Now, the binary image can be signed using mkfm. In the directory where the binary image is generated, execute:

mkfm -k SLOTID=<slot>/<fmsign> -f<sampleN.bin> -osampleN.fm

where “<slot>” is the slot id where the signing key is located and <fmsign> is the label of the private signing key that was previously generated and <sampleN> is the binary image of the sample FM being signed. This will generate a signed FM binary image, named “sampleN.fm”. This command requires the user password of the HSM partition to be entered.

4. Export the self-signed certificate to a file:

/usr/safenet/lunaclient/bin/cmu export -slot <slot> -password <userpin> -label <fmcert label> -outputfile=<fmcert.cert> 

5.Exit from all cryptoki applications that are still active, and load the FM image into the HSM. 

6.Execute this command:

ctfm i -a <HSM device #> -f<fmfilename>.fm -c <certificatefile>.cer

where certificatefile.cer is the name of the certificate in Admin Token used to verify the FM binary image integrity, and device # is the HSM number

if you have one PCIe HSM card it is device 0

a second HSM card would be device 1, and so on

if you want to load the FM on all FM-enabled HSM cards in the system, you can specify –A (as in ctfm i –A).

or, to load the FM and verify it using the public key in the certificate file, AND save the certificate object in the admin partition with the set label:

ctfm i -a <HSM device #> -f<fmfilename>.fm -c <certificatefile>.cer –l<CertObjectLabel>

but, if the certificate is already on the HSM slot/partition you can use

ctfm i -a <HSM device #> -f<fmfilename>.fm -l <CertObjectLabel>

7.The load operation can be checked by executing the command:

ctfm q

and ensuring that the FM name is correct, and the FM status is “Loaded”.

     For Luna Network HSM

1.From the Client, generate the key pair on the slot. Execute:

cmu generatekeypair -slot <slot> -password <userpin> -label <fmsign> -keytype <rsa> -sign <true> -verify <true> -modulusbits <2048>

This will generate a 2048 bit RSA key pair. The minimum key size for FM signing should be 2048 bits.

2.To obtain the handles of the new key objects. Execute:

cmu list -slot <slot> -password <userpin> -handle -class -label <fmsign>

3.To make a self signed certificate, execute:

cmu selfsigncertificate -slot <slot> -password <userpin> -publichandle <pubkeyhd1> -privatehandle <prikeyhd1> -label <fmcert> -cn <fmcert>

4.Now, the binary image can be signed using mkfm. In the directory where the binary image is generated, execute:

mkfm -k SLOTID=<slot>/<fmsign> -f<sampleN.bin> -osampleN.fm

where “<slot>” is the slot id where the signing key is located and <fmsign> is the label of the private signing key that was previously generated and <sampleN> is the binary image of the sample FM being signed. This will generate a signed FM binary image, named “sampleN.fm”. This command requires the user password of the HSM partition to be entered.

5. Export the self-signed certificate to a file:

/usr/safenet/lunaclient/bin/cmu export -slot <slot> -password <userpin> -label <fmcert label> -outputfile=<fmcert.cert> 

6.Copy the exported certificate file to the host of the HSM that is to use the FM, and copy the FM there as well. If the destination is a Luna Network HSM, use pscp or scp:  

scp <fmcert.cert> admin@<hostname-or-ip-of-appliance>:

7.On the network HSM, ensure that policy 51 is set for AutoActivation of Secure Memory File System (SMFS).

8.Exit from all cryptoki applications that are still active, and load the FM image into the HSM.

Log in via Luna Shell, with hsm login and execute:

hsm fm load -certFile <filename> -fmFile <filename>

The load operation can be checked by executing the command:

hsm fm status

9.To enable the newly signed FM you must restart the HSM.

hsm restart

NOTE   For Windows environments, set a search path to the libraries.

Example: for a default installation, set:

PATH=C:\Program Files\SafeNet\LunaClient\

and

LD_LIBRARY_PATH=C:\Program Files\SafeNet\LunaClient\

Adjust your path statement if you selected a non-default install path during Luna HSM Client software installation.