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.

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.