FM Samples

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.

Note that for running this sample TEST_RSA_KEY RSA key must be created. This may be achieved with the following command:

ctkmu c -nTEST_RSA_KEY -trsa -z1024 -aEDSUPT

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. Note that 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.

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.

NOTE

>This sample is included for Linux clients only.

>Warnings appear while compiling this sample. These warnings can be safely ignored.

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 Sample Directories

Each of the FM samples are structured in a similar way. In each sample directory there is -

>Makefile: makefile to build host and HSM side code

>Fm: directory holding HSM side source

>Host: directory holding host 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/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.

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

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

Please refer to ctcert for a full account of the ctcert utility.

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”.

FMs in Emulation Mode

When running FMs in emulation mode, the HSM Software Emulation library is used and the above steps for signing and installing the FM do not apply. The emulated HSM does require basic initialization using the same steps as a real HSM, as described in the ProtectToolkit-C Administration Guide.

1.Initialize the slot (0):

ctconf -n0

2.Initialize the slot's user PIN:

ctkmu p -s0

3.List slots:

ctkmu l

Emulation builds and test steps

make EMUL=1
cdfm/obj-linux-i386e
sampleN

Adapters builds and test steps

make 
cd obj-ppcfm
mkfm -k devel_key -f sampleN -o sampleN.fm
ctconf -j sampleN.fm
sampleN