FM samples

This section describes the sample FMs provided with the FM SDK, their directories, how to sign them, and how to run them in Emulation mode.

Included samples

The sample files included in the FM SDK are the following:

• RSAENC

• XORSign

• restrict

• safedebug

• cipherobj

• eccdemo

• oaepcipherobj

• smfs

• secfmenc

• ssldemo

• usbdemo

• javahsmreset

• javahsmstate

RSAENC

This sample demonstrates how custom functionality can be implemented with use of the RSA_Enc command.

This command combines several PKCS#11 commands such as C_Initialize, C_OpenSession, C_FindObjectsInit, C_FindObjects, C_EncryptInit, C_Encrypt, C_CloseSession in one single call.

XORSign

This sample demonstrates the addition of a new signing mechanism by patching existing PKCS#11 digest functions.

The new mechanism is bitwise exclusive OR with name CKM_XOR.

Execute the test app with -g to generate the required key:

xortest -g

restrict

This sample demonstrates restricting access to slot 0 by patching existing PKCS#11 C_OpenSession function.

safedebug

This sample demonstrates how to use SMFS storage to determine if your FM should abort its startup.

cipherobj

This sample demonstrates how to access primitive cryptographic services by using the cipher object system. To run this sample, TEST_DES3_KEY DES3 key must be created with the following command:

ctkmu c -nTEST_DES3_KEY -tdes3 -aEDSVT

The key must be marked as sensitive (-T) as this example also demonstrates the CT_SetPrivilegeLevel(PRIVILEGE_OVERRIDE) API.

eccdemo

This sample demonstrates how an FM uses ECDSA and EDDSA cipher objects. For more information about these cipher objects, refer to ECDSA cipher object and EDDSA cipher object respectively.

oaepcipherobj

This sample demonstrates how to access primitive cryptographic services by using the cipher object system in OAEP mode.

smfs

This sample demonstrates how to access the Secure Memory File System.

secfmenc

This sample demonstrates the use of the FMSC_SendReceive() function to call custom FMs using the Cryptoki library (see FMSC_SendReceive). It can perform RSA as well as DES3 encryption.

To run an RSA test, you must first have an RSA key with the label TEST_RSA_KEY stored on the HSM.

To run a DES3 test, you must first have a DES3 key with the label TEST_DES3_KEY stored on the HSM.

ssldemo

This sample is included as a reference for how to use the Big Number library (libfmbn) with your FMs.

usbdemo

This sample allows applications written using the USB API to interact with the HSM. You must load the usbdemo FM sample to use this functionality. See USB API reference for the available calls.

javahsmreset

This function does not make FMs.

This is a Java version of the function hsmreset, functionally identical to the ‘C’ hsmreset. This function demonstrates how to interface to the Java MD API (JHSM).Only the Java source code is provided. It is recommended that the THREADS_FLAG environment variable be set to native for Unix/Linux platforms.

javahsmstate

This function does not make FMs.

This is a Java version of the function hsmstate, functionally identical to the ‘C’ hsmstate. This function demonstrates how to interface to the Java MD API (JHSM). Only the Java source code is provided. It is recommended that the THREADS_FLAG environment variable is set to native for Unix/Linux platforms.

FM samples directory structure

The samples directory in the FM SDK package contains a set of subdirectories for each of the samples described in Included samples. All of the sample subdirectories are structured similarly and contain the following files and subdirectories:

• Makefile

• fm

• host

• include

Makefile

Makefile to build host and HSM-side code.

fm

Directory holding HSM-side source. It contains the following files:

hdr.c

Header file for the production build of the FM binary image.

sample.c

HSM side; main source for the FM.

Makefile

Makefile to build the FM and the application.

host

Directory holding host-side source. It contains the following files:

stub_sample.c

Host-side stub (request encoder or decoders) (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.

include

Optional directory to hold common header files.

Building sample FMs

This subsection describes the commands that are used to build the FM samples and the subdirectories that contain the binaries generated after running the build commands.

FM sample build commands

The samples are built using gnumake and the provided Makefiles. When working on a platform that has a native gnumake, such as Linux, you can use the system make command. When building the host part of the samples on Windows, a copy of gnumake is provided in <fm_installation_path>\bin.

• Production build, no debug information in binaries:

  make

• Production build, with debug information in binaries:

  make DEBUG=1

• Emulation build, no debug information in binaries:

  make EMUL=1

• Emulation build, with debug information in binaries:

  make EMUL=1 DEBUG=1

FM sample binary directories

Binary files generated by the above variants are placed in different directories. Therefore, all variants can be generated in the same directory. The directory names used are:

• obj-win32: Binaries for the production, non-debug host build on win32 environment

• obj-win32d: Binaries for the production, debug host build on win32 environment

• obj-linux-i386: Binaries for the production, non-debug host build on Linux/i386 environment

• obj-linux-i386d: Binaries for the production, debug host build on Linux/i386 environment

• obj-ppcfm: Binaries for the production, non-debug FM build for the HSM environment

• obj-ppcfmd: Binaries for the production, debug FM build for the HSM environment

• obj-linux-i386e: Binaries for the emulation, non-debug FM build on Linux/i386 environment

• obj-linux-i386ed: Binaries for the emulation, debug FM build on Linux/i386 environment

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

make EMUL=1 clean

Signing sample FMs

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 download them to the HSM.

To sign sample FMs

To use the key management scheme #1 (using self-signed FM download certificates), follow the steps listed below.

1. Generate the key/certificate pair on the first token. From a command prompt, execute:

   ctcert c -s0 -k -trsa -z2048 -lfm

   This will generate a 2048 bit RSA key pair, and a self-signed certificate. The minimum key size for FM signing is 2048 bits. The labels of the generated keys are as shown below:

   Private Key: fm (Pri)

   Public Key: fm (Pub)

   Certificate: fm

2. You must copy the certificate to the Admin Token. This can be done using by using ctcert to export the certificate to a file.

   ctcert x -lfm -s0 -ffmcert.crt

3. Then import the certificate to the Admin Token. For this operation, the password of the Admin Token is required.

   ctcert i -ffmcert.crt -s2 -lfm

4. You must mark the certificate as “Trusted”. This can be done using the ctcert utility with the ‘t’ command line option.

   ctcert t -lfm -s2

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

   mkfm -k “<TokenLabel>/<fm (Pri)>” -fsampleN -osampleN.fm

   where <TokenLabel> is the label of the token in Slot 0, <fm (Pri)> 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 token to be entered.

6. Exit from all cryptoki applications that are still active, and download the FM image to the HSM. Execute:

   ctconf -b<fm> -jsampleN.fm

   where <fm> is the name of the certificate in Admin Token used to verify the FM binary image integrity. After a while, the command will report a successful download. The download operation can be checked by executing the command:

   ctconf -s

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

Building and testing FMs in Emulation Mode

This section describes how to build and test FMs in Emulation Mode.

Prerequisites

• The emulated HSM requires basic token initialization like a physical ProtectServer 3 HSM. For more information, refer to Setting up slots and Token initialization.

• Move the FM samples directory out of the ProtectToolkit installation directory.

To build and test an FM in Emulation Mode

1. Navigate to the FM samples directory.

   Note

   The samples directory should have been moved outside the FM SDK installation directory before beginning the procedure. To avoid running into issues, move samples out of the installation directory before modifying, compiling, or running them.

   cd <path/to/samples>

   cd /opt/samples
   

2. Run an emulation build of the sample.

   make EMUL=1 <sample_name>

   make EMUL=1 cipherobj
   

   The sample binaries are generated in a subdirectory of fm.

3. Navigate to the directory containing the newly generated binaries. For a list of directory names that are generated, refer to FM sample binary directories.

   cd <sample_path>/fm/<directory_containing_binaries>

   cd cipherobj/fm/obj-linux-x86_64e
   

4. Set the path of LD_LIBRARY_PATH to the path containing the generated sample binaries.

   export LD_LIBRARY_PATH=.

   Tip

   On Ubuntu, run the following command:

   export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH

5. Run the sample.

   ./<sample_binary>

   ./cipherobjtest
   

After building and testing the FM in Emulation Mode, the FM is ready for deployment on a physical ProtectServer 3 HSM. For more information, refer to FM deployment.