Enable features on a network-attached HSM

Feature enabling differs for static and dynamic features.

  • You can enable static features from the front panel of the unit or from the client.

  • Entrust recommends that you enable dynamic features from the client. If the dynamic feature applies directly to nShield HSM, for example client licenses, you can use a nethsmadmin option to apply them.

When enabling static feature(s) from the front panel, either using a card or a file, the module is cleared without warning. This will cause the HSM to drop or restart any SEE machine, and lose all the application keys that were loaded. In some cases, applications may need to be restarted.

View enabled features

To see which (if any) features have already been enabled on the nShield HSM, from the main menu select HSM > HSM feature enable > View current state.

To print this list to a file on the unit, select HSM > HSM feature enable > Write state to file. The resulting file is transferred when the unit configuration is pushed to the remote file system. You can find it in /opt/nfast/kmdata/hsm-ESN/features/fet.txt (Linux) or %NFAST_KMDATA%\hsm-ESN\features\fet.txt.

Enable features with a smart card

To enable a new feature with a Feature Enabling smart card from Entrust:

  1. Insert the Feature Enabling smart card into the unit’s slot.

  2. From the front panel, select HSM > HSM feature enable > Read FEM from card.

A message is displayed if the features are enabled successfully. If you do not see this message confirming a successful upgrade, see Enabling features without a smart card.

Enabling features without a smart card

You can also provide the Feature Enabling Certificate information supplied by Entrust from a file.

To enable a feature without a smart card:

  1. Put the file that contains the feature enabling certificate in /opt/nfast/kmdata/hsm-ESN/features (Linux) or %NFAST_KMDATA%\hsm-ESN\features (Windows) on the remote file system. In this path, ESN is the ESN of the module.

    You can give the file any name that you wish. You must enter the file name on the unit’s front panel, so you may prefer to use a short name.

  2. From the front panel, select HSM > HSM feature enable > Read from a file.

  3. Specify the name of the file that contains the certificate.

If the feature is enabled successfully, a message confirms this.

Remotely enabling dynamic feature certificates including nShield HSM client licenses

Feature certificates contained on the remote file system (RFS) can be applied to the nShield HSM. The main use case for applying feature certificates is for enabling the client licenses dynamic feature which have been purchased after the initial nShield HSM purchase, although both static and other dynamic feature certificates can be applied.

If you have performed a factory reset of your HSM, ensure you re-enable any dynamic features.

To apply a dynamic feature certificate, such as an nShield HSM client license, do the following:

Feature certificates must be present on the RFS in the folder $NFAST_KMDATA/hsm-ESN/features.

  1. Use the nethsmadmin utility to list the nShield HSM feature files on the RFS. Run the command:

    nethsmadmin --module=<MODULE> --rfs=<RFS_IP> --list-features

    In this command:

    • <MODULE> specifies the HSM to use, by its ModuleID (default = 1).

    • <RFS_IP> specifies the IP address of the RFS.

    • Additionally the --rfs-hkneti=<RFS_HKNETI> and --rfs-esn=<RFS_ESN> options can be set to enable secure authentication of the RFS. There are three possible cases:

      • Without secure authentication: The authentication of the RFS will be based on the IP address only if the --rfs-hkneti and --rfs-esn options are not specified.

      • Software-based authentication: The --rfs-hkneti option specifies the software KNETI hash of the RFS. The --rfs-esn option shall not be specified.

        <RFS_HKNETI> can be obtained by running anonkneti -m0 localhost on the RFS.

      • nToken authentication: Only if an nToken (or local HSM) is installed in the RFS. The --rfs-hkneti and --rfs-esn options specify the KNETI hash and ESN of the nToken.

        <RFS_HKNETI> and <RFS_ESN> can be obtained by running ntokenenroll -H on the RFS.

  2. Use the nethsmadmin utility to make the nShield HSM use a specific feature file from the RFS. Run the command:

    nethsmadmin --module=<MODULE> --rfs=<RFS_IP> --apply-feature=<feature_file>

    In this command:

    • <feature_file> must be the path to the feature file that is displayed when you run the nethsmadmin command with the --list-features option. Errors are reported if you use either just the feature name, or the full path. The file must be alphanumeric, and no longer than 150 characters.

      The following is an example of the output expected when applying a dynamic feature:

      Applying feature <DYNAMIC_FEATURE> to module <MODULE_NO> ...
Feature <DYNAMIC_FEATURE> application process started on module <MODULE_NO>
*DYNAMIC_FEATURE DETECTED*
Please restart you clientside hardserver and check the enquiry output to ensure the dynamic feature has been applied correctly!
For the client licences feature check the 'max exported modules' section in enquiry to see if the new client number has been applied correctly.

      The following is an example of the output expected when applying a static feature:

      Applying feature <STATIC_FEATURE> to module <MODULE_NO> ...
Feature <STATIC_FEATURE> application process started on module <MODULE_NO>
*STATIC_FEATURE DETECTED*
To be able to use the static feature please clear module MODULE_NO.
Use the fet utility to verify the feature was applied correctly.

      In the output examples:

    • <DYNAMIC_FEATURE> specifies the name of the dynamic feature file applied.

    • <STATIC_FEATURE> specifies the name of the static feature file applied.

    • <MODULE_NO> specifies the HSM that the feature was applied to.