FM Deployment
This chapter provides an overview of how to deploy an FM on an HSM device. The ProtectToolkit-C Administrator can deploy FMs using the Functionality Module Manager (ctfm). For more information about the ctfm utility, see ctfm.
It contains the following sections:
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 Thales 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
NOTE
>The output file name must be a .fm file.
>The slot must have a token name implemented or the mkfm command will fail.
>The minimum key size for FM signing is 2048 bits.
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. Note the following:
>Each FM must have a unique FMID.
>The FMID must be compiled into the FM as part of the FM image.
>You must use the FMID when calling the FM.
Configuring a unique FMID
Before you compile your FM, you must assign a unique FMID to it by defining the MY_FM_NUMBER macro in the 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 MY_FM_NUMBER value.
#define MY_FM_NUMBER <FMID>
NOTE The MY_FM_NUMBER value must be input as a hexadecimal value from 0x100 to 0xffff (values below 0x100 are unavailable). Subsequent calls to the FM must be directed towards the FMID value. For example, an hdr.c MY_FM_NUMBER value of 0x100 results in an FMID of 256. The ctfm and ctconf utilities display FMIDs in hex mode.
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_SendReceive.
>You must use the correct FMID when registering a custom command handler in the FM startup.
Examples
This example demonstrates an FM that has been assigned an FMID of 0x300.
>Configuration of the FM hdr.c file.
#define MY_FM_NUMBER 0x300 DEFINE_FM_HEADER(MY_FM_NUMBER, FM_VERSION, FM_SER_NO, FM_MANUFACTURER, FM_NAME);
>Using the FMID value in the host application MD_SendReceive.
rv = MD_SendReceive( adapter, originatorID, MY_FM_NUMBER, request, RESERVED, reply, &recvLen, &appState);
