ctfm
Functionality Module Management utility for the ProtectToolkit-C environment.
The ctfm utility is restricted to use by the ProtectToolkit-C administrator, to manage functionality modules on ProtectServer devices (HSMs).
With this tool it is possible to:
>Load a new FM (if a patched FM is already loaded, it is overwritten)
>Delete an FM so it becomes inactive
>Query the status of an FM (if any)
>Verify an FM file is correctly signed
In each case, the operation may apply to all HSMs or an individually-specified HSM.
Starting with ProtectToolkit version 5.4, you can upload multiple custom FMs to an HSM and use them simultaneously. 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 Functionsand PKCS#11 Patched Functions for descriptions of these FM types.
By default, ctfm will report the FM state for the first device found.
The device Administrator PIN and Admin SO PIN must be initialized in order to run these commands. The ctfm utility will prompt the operator for new PINs if they are not initialized.
When the commands are executed, they may require the Admin PIN or Admin SO PIN. The utility will prompt the operator for the values (unless the values have been previously entered during execution of the same command).
Event log entries are created when FMs are loaded or disabled. To create event logs correctly, the HSM RTC should be initialized. If the ctfm utility detects that the RTC is not initialized, it will request approval to initialize the HSM RTC to match the system clock.
To load an FM, a trusted certificate must be present in the Admin Token of the HSM. Usually, a PEM-encoded certificate file is provided with the FM image file. If the utility detects that the certificate is not present, it will import the certificate from the file into the Admin Token and set it to Trusted.
NOTE When operating in WLD/HA mode, this utility should only be used to view the configuration. Any changes to the configuration should be made in NORMAL mode. See Operation in WLD Mode and Operation in HA Mode for more information about these operating modes.
Syntax
Delete FM
ctfm d -i<fmID> [-a<device>|-A]
Import FM
ctfm i -l<certLabel> -f<fmFile> [-a<device>|-A] [-c<certFile>]
Query FM status
ctfm q [-a<device>|-A]
Verify an FM file
ctfm v-f<fmFile> -l<certLabel> [-a<device>|-A] [-c<certFile>]
Commands
| Command | Description |
|---|---|
| d |
Delete FM This command is used to delete an FM so it becomes inactive on one or all HSMs. You must specify the FM's hex ID with the -i<fmID> option. |
| i |
Import FM This command is used to load a new FM onto one or all HSMs. Starting with ProtectToolkit version 5.4, you can upload multiple custom FMs to an HSM and use them simultaneously. 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 Functionsand PKCS#11 Patched Functions for descriptions of these FM types. Existing FMs do not need to be disabled prior to executing this command. The command searches the device's Admin Token for a certificate label equal to the <certLabel> parameter. If the certificate object is present, the utility will ensure the certificate is set to Trusted. If the certificate object is not present, the utility will attempt to create a Trusted certificate from the contents of the <certFile>. If the <certFile> parameter is not provided, the utility will assume the filename is the <certLabel> with ".cert" appended. For example, if the certificate label is myfm then the utility will search for a file named myfm.cert. The device Administrator PIN (and possibly the Admin SO PIN) will be required. |
| q |
Query FM Status This is the default command, used to query the status of an FM (if any) on one or all HSMs. Use this command to obtain the name, version information and disable status of an FM or to see if an FM is loaded at all. No PINs are required to perform this operation. |
| v |
Verify an FM Signature This command is used to verify that an FM file has been signed correctly, without attempting to download the FM. The device Administrator PIN will be required. The behavior of the <certLabel> and <certFile> parameters is the same as for the Import FM command above. |
Options
The following options are supported:
| Option | Description |
|---|---|
| -a<device> |
--device-number=<device> Use the Admin Token on the specified device. The first device is numbered 0. If this option is absent then the first device is implied. |
| -A |
--all-devices Apply command to all available devices. |
| -c<certFile> |
--fm-cert-file=<certFile> FM validation certificate filename. |
| -f<fmFile> |
--fm-file=<fmFile> Name of file holding a new FM. |
| -h,-? |
--help Display usage information. |
| -i<fmID> |
--fmid=<fmID> Specifies the FM ID in hex format. |
| -l<certLabel> |
--fm-cert-label=<certLabel> FM validation certificate object label. |
