FM Deployment

This chapter provides an overview of how to deploy an FM on an HSM device. The SafeNet ProtectToolkit-C Administrator can deploy FMs using the Functionality Module Manager (ctfm). See CTFM for more information about the ctfm utility.

It contains the following sections:

>Deploy a Single FM

>Deploy Multiple FMs

NOTE   Only one PKCS#11 patched FM can be loaded and used at a time. If a patched FM is already loaded, it is overwritten by the new FM. Refer to Custom Functions and PKCS#11 Patched Functions for more information about these FM types.

Deploy a Single FM

To use an FM you must sign the FM binary and load the signed .fm file onto the HSM. The process consists of the following:

1.Compile the FM using make.

2.Sign the compiled FM using mkfm.

3.Load the FM onto the HSM using ctfm.

NOTE   Gemalto recommends deploying FMs in a test environment before delivering to a production environment.

To compile the FM

1.Navigate to the directory where the FM binary components are stored.

2.Use make to compile the FM.

To sign a compiled FM

1.Navigate to the directory containing the FM binary image.

2.Use mkfm to sign the FM and generate a .fm file.

mkfm -kSLOTID=<HSMslotID>/<PrivateKeyLabel> -f <fmBinary> -0 <fmFile>.fm

3.Use ctcert to import the certificate into the Admin slot

ctcert i -f<certificate_file> -l<certificate_label> [-s<admin_slot>]

4.Use ctcert to make the certificate trusted.

ctcert t -l<certificate_label> [-s<admin_slot>]

To load the FM onto the HSM

1.Navigate to the directory where the .fm file is stored. Use ctfm to load the .fm onto the HSM.

ctfm i -a<device> -l <certLabel> -f<.fmFile>

2.Run ctfm q -a<device> to confirm that the FM was loaded successfully.

ctfm q -a<device>

Deploy Multiple FMs

To deploy multiple FMs you must sign the FM binary and load the signed .fm file onto the HSM. Also:

>Each FM must have a unique FMID.

>The FMID must be compiled into the FM as part of the FM image header hdr.c file.

>You must use the FMID when calling the FM.

Configuring a unique FMID

Before you compile your FM, you must redefine the FM_NUMBER_CUSTOM_FM macro in the FM hdr.c file. Subsequently, you compile the FM using make, sign the FM binary, and load the .fm file onto the HSM.

To configure a unique FMID

1.Open the FM hdr.c file in a text editor. Add the following line to define the FM_NUMBER_CUSTOM_FM value.

#define FM_CUSTOM_NUMBER_FM <FMID>

NOTE   The FM_CUSTOM_NUMBER_FM value must be input as a hexadecimal value. Subsequent calls to the FM must be directed towards the FMID value. For example, an hdr.c FM_CUSTOM_NUMBER_FM value of 0x096 results in an FMID of 60.

Calling FMID

On an HSM device with multiple loaded FMs you must direct calls towards the unique FMID. Adhere to the following:

>You must use the FMID value to register any dispatch using FMSW_REGISTERDISPATCH

>You must use the FMID value for any host application such as MD_SENDRECIEVE.

>You must use the correct FMID when registering a custom command handler in the FM startup.

Examples

This example demonstrates using the FMID value to register any dispatch using FMSW_REGISTERDISPATCH.

#include <fmsw.h>

FMSW_STATUS FMSW_RegisterDispatch (

FMSW_FMNumber_t <FMID>,

FMSW_DispatchFn_t dispatch);

This example demonstrates using the FMID value in the host application MD_SENDRECEIVE.

MD_RV MD_SENDRECEIVE(uint32 hsm index,

                     uint32 originatorId,

                     uint16 <FMID>,

                     MD_Buffer_t* pReq,

                     uint32 timeout,

                     MD_Buffer_t*pResp,

                     uint32* pReceivedLen,

                     uint32* pFmStatus);