ctfm

Functionality module (FM) 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.

You can upload up to 12 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 functions and 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.

Syntax

The following ctfm syntax can can be used.

Commands

The following ctfm commands are available.

d

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

This command is used to load a new FM onto one or all HSMs.

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 functions and 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

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

This command is used to verify that an FM file has been signed correctly, without attempting to download the FM. The behavior of the <certLabel> and <certFile> parameters is the same as for the ctfm i command above.

The device Administrator PIN is required.

Options

The following ctfm options are available.

-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.