ctfm
Functionality Module Management utility.
SYNTAX
ctfm d [-a<device> | -A | -s#]-i<fmid> [-p<password> | -e<PED>] ctfm i [-a<device> | -A | -s#] [–c<certFile>] [-l<certLabel>] -f<fmFile> [-p<password> | -e<PED>] ctfm q [-a<device> | -A | -s#] ctfm v [-a<device> | -A | -s#] [–c<certFile>] -l<certLabel> -f<fmFile> [-p<password> | -e<PED>] ctfm a [-a<device> | -A | -s#] [-n] [-p<password> | -e<PED>]
DESCRIPTION
The ctfm utility is designed for the HSM administrator and is used to manage functionality modules on the HSMs.
NOTE This tool is for use on a computer that hosts a Luna PCIe HSM locally. For Luna Network HSMs, use the LunaSH hsm fm commands.
With this tool it is possible to:
>Load a new FM
>Delete an FM
>Query the status of any FMs
>Verify an FM file is correctly signed
>Activate the SMFS on an HSM.
In each case the operation may apply to all HSMs or an individually specified HSM. By default, ctfm reports the FM state for all devices found.
The device Security Officer password must be initialized in order for these commands to run. When the commands are executed they might require the SO password of the HSM. When it is required, the utility prompts the operator for the values (unless the values have already been entered during the execution of the same command, or provided by the -p option).
Audit trail entries are created when FMs are loaded or disabled. In order to create event logs correctly the HSM real time clock should be initialized.
NOTE To set the real time clock, and enable audit entries, initialize the Auditor Role.
In order to load an FM, a certificate must be present in the Admin Token of the HSM. Usually a PEM-encoded certificate file is provided with the FM image file that you can load to the HSM Admin slot with the cmu tool.
If the utility detects that the certificate is not already present in the Admin token, the utility imports the certificate from the cert file.
If no Certificate label is specified then a Certificate file name must be specified and the ctfm utility creates a temporary cert object from the file contents.
FM STATES
Each FM in the HSM has a certain state.
| Enabled | The FM is in memory and has been started. On HSM restart the FM will return back to the Enabled state. |
| Zombie | The FM is in memory and has been started. On HSM restart the FM will disappear |
| Loaded | The FM is not in memory and has not been started. After next HSM restart the FM will go to the Enabled state. |
| InActive | The FM is loaded but has not been started because it is waiting for the SMFS Activation. |
| Not started | The FM is loaded but failed to start – this could be due to the HSM FW version being too old for the FM. |
COMMANDS
d Disable/Delete FM
ctfm d [-a<device> | -A] [-i <fmid>] [-p <password | -e<PED>]
This command is used to remove an FM.
The exact behaviour depends on the state of the FM.
| Enabled | FM changed to zombie state |
| Zombie | No action |
| Loaded | FM will be deleted |
NOTE The HSM SO PIN will be required.
i Import FM
ctfm i [-a<device> | -A] [–c<certFile>] [-p <password> | -e<PED>] [-l<certLabel>] -f<fmFile>
Load a new FM onto an HSM.
The FM image file contains an FM image and a digital signature. The import operation directs the image and signature to the appropriate Public Key Certificate file which is used to verify the signature. The command looks on the Admin Token of the device for a certificate label equal to the <certLabel> parameter.
If the certificate object is not present then the utility will attempt to create a certificate object from the contents of the certFile i.e. import the certificate
If the <certFile> parameter is not provided the utility will assume the filename is the <certLabel> with .cert or .crt appended. For example, if the certificate label is myfm then the utility will search for a file named myfm.cert and then myfm.crt.
The exact behavior of the command depends on the state of other FMs in the HSM:
>The FM will be installed in the HSM in a Loaded state.
>If a FM with the same ID and in a Loaded state is already in the HSM then the new FM will replace the old FM, and the old FM will enter a Zombie state.
>If a FM with the same ID and in a Enabled/Zombie state is already in the HSM then the old FM changes to or remains in Zombie state.
The exact behavior depends on the state of the HSM:
| Enabled | HSM restart will restore all Enabled FMs |
| Zombie | HSM restart will delete all Zombie FMs |
| Loaded | HSM restart will enable all Loaded FMs |
NOTE The HSM SO PIN will be required.
q Query FM Status
ctfm q [-a<device> | -A]
Queries the status of an FM (if any) on all or an individual HSM.
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.
NOTE If the FM state is Enabled but the Status shows an error then it might not be possible to communicate with any FM. You should use ctfm to delete the failing FM.
No PINs are required to perform this operation.
v Verify an FM Signature
ctfm v [-a<device> | -A] [–c<certFile>] [-p <password> | -e<PED>] -l<certLabel> -f<fmFile>
This command is used to verify that an FM file has been signed correctly without attempting to load the FM.
The HSM SO PIN is required.
The behaviour of the <certLabel> and <certFile> parameters is the same as is described for the Import FM command above.
a Activate SMFS
ctfm a [-a<device> | -A] [-p <password> | -e<PED>] [-n]
This command activates the Secure Memory File system.
Either the HSM SO or Administrator user can activate the SMFS. Default is SO. Specify administrator with "-n".
OPTIONS
The following options are supported:
| Parameter | Shortcut | Description |
|---|---|---|
| --device-number=<device> | -a | Use the admin token on the specified device. The first device is numbered 0. If this parameter is absent then the first device is implied. This option is useful in case of more than one HSM in the host. |
| --all-devices | -A | Apply command to all available devices. |
| --slot=<slotNum> | -s | Apply command to Device with Cryptoki slot number. |
| --fmid=<id> | -i | Specify ID (in HEX) of FM (default 0x100). |
| --fm-cert-file=<name> | -c | FM validation certificate filename. |
| --fm-file=<name> | -f | Name of file holding a new FM. |
| -help | -h, -? | Display usage information. |
| --fm-cert-label=<name> | -l | FM validation certificate object label. |
| --password=<password> | -p | SO or Admin password – if this option is not included in the command, then ctfm may prompt for the password. Not valid where a PED prompt is required. |
| --administrator | -n | Use Administrator role instead of SO (SMFS activation only). |
| --no-banner | -b | Do not show program banner during startup. |
| --ped=<PED> | -e | Remote PED ID. Default is 0 (zero). Check lunacm to find the value (usually 100) to insert here. |
