Creating and managing a Security World

This chapter describes how to create and manage a Security World. You must create a Security World before using the HSM to manage keys.

You normally create a Security World after installing and configuring the module and its software. For more information, see:

You create a Security World with a single HSM. If you have more than one module, select one module with which to create the Security World, then add additional modules to the Security World after its creation. For more information, see Adding or restoring an HSM to the Security World. If you create a Security World with the audit logging feature enabled, all additional HSMs added to this Security World will also have audit logging enabled.

To use the module to protect a different set of keys, you can replace an existing Security World with a new Security World.

For more information about the type of user that is required for different operations, see About user privileges.

All Security Worlds rely on you using the security features of your operating system to control the users who can access the Security World and, for example, write data to the host.

Creating a Security World

You can use the following to create Security Worlds:

The creation process

When you create a Security World:

  • The HSM is erased

  • A new HSM key for this Security World is generated

  • A new ACS to protect this HSM key is created

  • The Security World information is stored on hard disk of the host computer

    • The information is encrypted using the secrets stored on the ACS

  • The HSM and Security World are configured for Audit Logging if selected

    If you want to re-use the physical cards created in a previous Security World, you must erase all Operator Cards, except for nShield Remote Administration Cards, while the previous Security World still exists. See Erasing cards and softcards.
    We recommend that you regularly back up the entire contents of the RFS. Either the %NFAST_KMDATA% directory on Windows, or the kmdata directory on Linux, is required to restore an nShield HSM or its replacement, to the current state in case of failure.
    Due to the additional primality checking required by SP800-131A, Security World generation will take longer when using the new default Ciphersuite (from v12.40 onwards) - on nShield USB-attached HSMs, this could be up to 45 minutes.

Security World Files

The Security World infrastructure stores encrypted key material and related data in files on the host. For multiple hosts to use the same Security World, the system administrator must ensure that these files are copied to all the hosts and updated when required.

Location of Security World files

The logic for finding the security world data directory is:

  1. If NFAST_KMLOCAL is set, use that.

  2. Otherwise, if NFAST_KMDATA is set, use ${NFAST_KMDATA}/local on Linux, %NFAST_KMDATA%\local on Windows.

  3. Otherwise, if NFAST_HOME is set, use ${NFAST_HOME}/kmdata/local on Linux, %NFAST_HOME%\kmdata\local on Windows.

  4. Otherwise, use /opt/nfast/kmdata/local on Linux, C:\nfast\kmdata\local on Windows.

By default, the Key Management Data directory, and sub-directories, inherit permissions from the user that creates them. Installation of the Security World Software must be performed by a user with Administrator rights that allow read and write operations, and the starting and stopping of applications.

Security World operations create or modify Security World files as follows:

Operation creates/modifies file(s)

Create a Security World

creates

world

(for each module in the Security World) module_ESN

Load a Security World

creates or modifies

(for each module in the Security World) module_ESN

Replace an ACS

modifies

world

Create an OCS

creates

card_HASH

cards_HASH_NUMBER

Create a softcard

creates

softcard_HASH

Generate a key

creates

key_APPNAME__IDENT

Recover a key

modifies

key_APPNAME (for each key that has been recovered)

  • <ESN> - Electronic serial number of the module on which the Security World is created.

  • <IDENT> - Identifier given to the card set or key when it is created.

  • <NUMBER> - Number of the card in the card set.

  • <APPNAME> - Name of the application by which the key was created. It’s a 40-character string that represents the hash of the card set’s logical token. It’s either user supplied or a hash of the key’s logical token, depending on the application that created the key.

Required files

The following files must be present and up to date in the directory, or the directory specified by the NFAST_KMLOCAL environment variable, for a host to use a Security World:

  • world

  • A module_ESN file for each module that this host uses

  • A cards_<IDENT> file for each card set that is to be loaded from this host

  • A card_<IDENT>_NUMBER file for each card in each card set that is to be loaded from this host

  • A key_<APPNAME>_<IDENT> file for each key that is to be loaded from this host.

These files are not updated automatically. You must ensure that they are synchronized whenever the Security World is updated on the module.

Security World options

Decide what kind of Security World you need before you create it. Depending on the kind of Security World you need, you can choose different options at the time of creation. For convenience, Security World options can be divided into the following groups:

  • Basic options, which must be configured for all Security Worlds

    • Optionally enable Audit Logging for the Security World

  • Recovery and replacement options, which must be configured if the Security World, keys, or passphrases are to be recoverable or replaceable

  • SEE options, which only need be configured if you are using CodeSafe

  • Options relating to the replacement of an existing Security World with a new Security World.

Security World options are highly configurable at the time of creation but, so that they will remain secure, not afterwards. For this reason, we recommend that you familiarize yourself with Security World options, especially those required by your particular situation, before you begin to create a Security World.

Security World basic options

When you create a Security World, you must always configure the basic options described in this section.

Cipher suite

Only one Cipher suite is supported and this is SP800-131 compliant.

ACS quorum

You must decide the total number of cards (N) in a Security World’s ACS and must have that many blank cards available before you start to create the Security World. You must also decide how many cards from the ACS must be present (K) when performing administrative functions on the Security World.

We recommend that you do not create ACSs for which K is equal to N, because you cannot replace such an ACS if even 1 card is lost or damaged.
In Common Criteria CMTS Security Worlds the minimum value of K for the ACS is 2.

In many cases, it is desirable to make K greater than half the value of N (for example, if N is 7, to make K 4 or more). Such a policy makes it harder for a potential attacker to obtain enough cards to access the Security World. Choose values of K and N that are appropriate to your situation.

The total number of cards used in the ACS must be a value in the range 1 – 64.

FIPS 140 Level 3 compliance

By default, Security Worlds are created to comply with the roles and services, key management, and self-test sections of the FIPS 140 standard at Level 2. However, you can choose to enable compliance with the FIPS 140 standard at Level 3.

This option provides compliance with the roles and services of the FIPS 140- 2 Level 3 standard. It is included for those customers who have a regulatory requirement for compliance.

If you enable compliance with FIPS 140 Level 3 roles and services, authorization is required for the following actions:

  • Generating a new OCS

  • Generating or importing a key, including session keys

  • Erasing or formatting smart cards (although you can obtain authorization from a card you are about to erase).

In addition, you cannot import or export private or symmetric keys in plain text.

UseStrongPrimes Security World setting

From firmware version 12.70, the nShield HSM always targets FIPS 186-4 compliance when generating RSA keys of 1024 bits or more. It typically does this using a "strong primes" strategy, however Entrust only guarantees this strategy if the UseStrongPrimes setting is enabled.

If your firmware is version 12.70 or higher, you do not need this setting enabled for FIPS 186-4 compliance.

If you are using an older version of firmware, meaning it has a version number lower than 12.70, then you need the UseStrongPrimes setting enabled to grant FIPS 186-2 compliance.

If your Security World is FIPS 140 Level 3, then this setting is on by default. If your Security World is not FIPS 140 Level 3, then you can disable the UseStrongPrimes setting for faster RSA key generation, however this removes FIPS 186-2 compliance.

Remote Operator

To use a module without needing physical access to present Operator Cards, you must enable the Remote Operator feature on the module. For more information, see Enabling optional features.

By default, modules are initialized into Security Worlds with remote card set reading enabled. If you add a module for which remote card reading is disabled to a Security World for which remote card reading is enabled, the module remains disabled.

OCS and softcard replacement

By default, Security Worlds are created with the ability to replace one OCS or softcard with another. This feature enables you to transfer keys from the protection of the old OCS of softcard to a new OCS or softcard.

You can replace an OCS with another OCS, or a softcard with another softcard, but you cannot replace an OCS with a softcard or a softcard with an OCS. Likewise, you can transfer keys from an OCS to another OCS, or from a softcard to another softcard, but you cannot transfer keys from an OCS to a softcard or from a softcard to an OCS.

You can choose to disable OCS and softcard replacement for a Security World when you create it. However, in a Security World without this feature, you can never replace lost or damaged OCSs; therefore, you could never recover the keys protected by lost or damaged OCSs, even if the keys themselves were generated as recoverable (which is the default for key generation).

OCS and softcard replacement cannot be enabled after Security World creation without reinitializing the Security World and discarding all the existing keys within it.

For an overview of Security World robustness and OCS or softcard replacement, see Replacing an Operator Card Set or recovering keys to softcards. For details about performing OCS and softcard replacement operations, see Replacing Operator Card Sets and Replacing the Administrator Card Set.

passphrase replacement

By default, Security Worlds are created so that you cannot replace the passphrase of a card or softcard without knowing the existing passphrase.

However, you can choose to enable passphrase replacement at the time you create a Security World. This option makes it possible to replace the passphrase of a card or softcard even if you do not know the existing passphrase. Performing such an operation requires authorization from the Security World’s ACS.

For details about performing passphrase replacement operations, see Changing unknown or lost passphrase.

Nonvolatile memory (NVRAM) options

Enabling nonvolatile memory (NVRAM) options allows keys to be stored in the module’s NVRAM instead of in the Key Management Data directory of the host computer. Files stored in the module’s non-volatile memory have Access Control Lists (ACLs) that control who can access the file and what changes can be made to the file. NVRAM options are relevant only if your module’s firmware supports them, and you can store keys in your module’s NVRAM only if there is sufficient space.

When the amount of information to be stored in the NVRAM exceeds the available capacity, you can instead store this data in a blob encrypted with a much smaller key that is itself then stored in the NVRAM. This functionality allows the amount of secure storage to be limited only by the capacity of the host computer.

Security World SEE options

You must configure SEE options if you are using the nShield Secure Execution Engine (SEE). If you do not have SEE installed, the SEE options are irrelevant.

SEE debugging

SEE debugging is disabled by default, but you can choose whether to enable it for all users or whether to make it available only through use of an ACS. In many circumstances, it is useful to enable SEE debugging for all users in a development Security World but to disable SEE debugging in a production Security World. Choose the SEE debugging options that best suit your situation.

Real-time clock (RTC) options

Real-time clock (RTC) options are relevant only if you have purchased and installed the CodeSafe Developer kit. If so, by default, Security Worlds are created with access to RTC operations enabled. However, you can choose to control access to RTC operations by means of an ACS.

Security World replacement options

Options relating to Security World replacement are relevant only if you are replacing a Security World.

If you replace an existing Security World, its directory is not overwritten but renamed (where N is an integer assigned depending on how many Security Worlds have been previously saved during overwrites). A new Key Management Data directory is created for the new Security World. If you do not wish to retain the directory from the old Security World, you must delete it manually.

Creating a Security World using new-world

Before you start

Before you start to create a Security World:

  • The HSM must be in pre-initialization mode. See Checking and changing the mode on an nShield Edge for more about changing the mode.

  • You must be logged in to the host computer as or as a user in the group nfast. For more information, see server_settings.

  • Before configuring the Security World, you should know:

    • The security policy for the HSM

    • The number and quorum of Administrator Cards and Operator Cards to be used

    To help you decide on the Security World you require, see Security World options.

  • You must have enough smart cards to form the Security World’s card set.

When you have finished creating a Security World, you must change the mode to "Operational" using nopclearfail -I m1 or nopclearfail -O -m1.

Follow the directions in this section to create a Security World from the command line with the new-world utility.

Running the new-world command-line utility

Open a command prompt window and type the command new-world using the options in the table.

The example below will create a Security World supporting FIPS140 Level 3 with a ACS quorum of 3/5 and with audit logging enabled.

new-world --mode=fips-140-level-3 --acs-quorum=3/5 --audit-logging

In this command:

Option Description

--initialize

This option creates a new Security World, replacing any existing directory.

Replacing an existing Security World in this way does not delete the Security World’s host data and recovery and replacement data, but renames the existing directory in which these reside as (where N is an integer assigned depending on how many Security Worlds have been previously saved during overwrites).

--factory

This option erases an HSM, restoring it to factory state.

--no-remoteshare-cert

This option prevents making the HSM from becoming a target for remote shares.

--no-strict-rsa-keygen

If you have not specified a mode parameter you can use the -no-strict-rsa-keygen flag to disable the UseStrongPrimes setting. Otherwise it will be enabled by default. See UseStrongPrimes Security World setting.

--mode=MODE

FIPS-140-level-3 creates a Security World compliant with FIPS 140 Level 3.

common-criteria-cmts creates a Security World supporting Common Criteria PP 419 221-5.

Omitting this option will create a default Security World compliant with FIPS 140 Level 2.

--no-recovery

This option disables the ability to recovery or replace OCSs and softcard (which is otherwise enabled by default). This is equivalent to setting !r, where the ! operator instructs the system to turn off the specified feature (r).

By default, new-world creates key recovery and replacement data that is protected by the cryptographic keys on the ACS. This option does not give Entrust or any other third party access to your keys. Keys can only be recovered if authorization from the ACS is available. We recommend that you leave OCS and softcard recovery and replacement functionality enabled.

We recommend that you do not disable the recovery and replacement option.
If you set the --no-recovery option, you can never replace lost or damaged OCSs generated for that Security World. Therefore, you could never recover any keys protected by lost or damaged OCSs, even if the keys themselves were generated as recoverable (which is the default for key generation).
OCS and softcard replacement cannot be enabled after Security World creation without reinitializing the Security World and discarding all the existing keys within it.

--cipher-suite=<CIPHER-SUITE>

This option specifies the Cipher suite and type of key that is used to protect the new Security World. <CIPHER-SUITE> should be set to DLf3072s256mAEScSP800131Ar1.

--nso-timeout=<TIMEOUT>

This option allows you to specify the time-out (<TIMEOUT>) for new Security Worlds. By default, an integer given for TIMEOUT is interpreted in seconds, but you can supply values for TIMEOUT in the form N s, N h, or N d where N is an integer and s specifies second, h specifies hours, and d specifies days.

--module=<MODULE>

This option specifies the module to use (by its ModuleID). If you have multiple modules, new-world initializes them all together.

--acs-quorum=<K>/<N>

In this option, <K> specifies the minimum number of smart cards needed from the ACS to authorize a feature. You can specify lower K values for a particular feature. All the K values must be less than or equal to the total number of cards in the set. If a value for K is not specified, new-world creates an ACS that requires a single card for authorization.

When the Security World is created in common-criteria-cmts mode, new-world requires a minimum K of 2.
Some applications do not have mechanisms for requesting that cards be inserted. Therefore any OCSs that you create for use with these applications must have K=1.

<N> specifies the total number of smart cards to be used in the ACS. This must be a value in the range 1 – 64. If a value for this option is not specified, new-world creates an ACS that contains a single card.

We recommend that you do not create an ACS for which the required number of cards is equal to the total number of cards because you will not be able to replace the ACS if even a single card is lost or damaged.

This option only takes effect if you are creating a new Security World.

--reduced-features

This option instructs new-world to use a reduced default feature set when creating a Security World. A Security World created with the --reduced-features option has no passphrase recovery; no NVRAM, RTC, or FTO; and no NSO delegate keys. However, such a reduced-features Security World can perform many operations faster than more fully featured Security Worlds.

--disablepkcs1pad

This option disables the use of PKCS#1 v1.5 padding. All attempts to use PKCS#1 v1.5 padding for encryption or decryption operations will be rejected.

PKCS#1 v1.5 signature operations are not affected.

PSS and OAEP are not affected.

--pp-min=LENGTH

This option enables a minimum passphrase length check for the Administrator Card Set (ACS) the Operator Card Set (OCS) and any associated softcards when you create a Security World. The minimum passphrase length check is then applied after the Security World is created. When enabled and you attempt to create a card passphrase with fewer characters than the specified minimum length, the following warning message displays:

Warning: short passphrase.

However, the passphrase can still be used.

Example:

new-world --initialize --acs-quorum=K/N   --pp-min=14

If --pp-min=<length> is not used, the minimum passphrase length is set to the default value (0).

–-pp-strength

This option enables passphrases to have at least one uppercase, lowercase, number, and symbol.

If the –-pp-strength argument is omitted, the complexity requirements are not enforced.

--audit-logging

This option configures the Security World and the HSM on which it is being created for audit logging, creating a log signing key for each HSM.

The log destination must have already been set in the hardserver configuration file. See Audit Logging.

Audit logging is automatically enabled when the Security World is created in common-criteria-cmts mode.

--max-keyusage

This option allows the administrator to specify a maximum reauthorization condition in terms of number of key usages since authorization for Assigned keys in common-criteria-cmts mode. A use limit compatible with the specified maximum will be applied at key creation time and can be verified for Assigned keys. If this is not set then no --max-keyusage limit is applied to Assigned keys on creation.

--max-keytimeout

This option allows the administrator to specify a maximum reauthorization condition in terms of a TIMEOUT since authorization for Assigned keys in common-criteria-cmts mode. By default, an integer given for TIMEOUT is interpreted in seconds, but you can supply values for TIMEOUT in the form Ns, Nh, or Nd where N is an integer and s specifies second, h specifies hours, and d specifies days. A use limit compatible with the specified maximum will be applied at key creation time and can be verified for Assigned keys. If this is not set then no limit is applied to Assigned keys on creation.
The --max-keyusage and --max-keytimeout options are only available in common-criteria-cmts mode. They provide support for the Protection Profile requirement that reauthorization conditions are set by an administrator on creating an Assigned Key.

new-world command-line utility features

Features for the Security World can be specified using the command line.

Security world features are selected by feature expressions. A feature expression is a comma-separated list of feature terms. Each term consists of a feature name, optionally preceded by either a double dash --, an exclamation point !, or no- to turn off the feature, and optionally followed by an equals sign = and the quorum of cards from the ACS required to use the feature. The default quorum is taken from the K argument of the --acs-quorum option.

If you set the !fto flag, that is, turn off FTO, you will not be able to use smart cards to import keys.
To use extended debugging for the HSM, you must set the dseeall flag.

The following feature names are available:

Feature name Description

m

This feature makes it possible to add new HSMs into the Security World. This feature cannot be disabled.

r

This feature enables OCS and softcard replacement; see Replacing Operator Card Sets.

p

This feature enables passphrase replacement; see passphrase replacement and Changing card and softcard passphrase.

nv

This feature specifies that ACS authorization is needed to enable nonvolatile memory (NVRAM) allocation.

rtc

This feature specifies that ACS authorization is needed to set the real-time clock (RTC), see Real-time clock (RTC) options.

dsee

This feature specifies that that ACS authorization is needed to enable SEE World debugging.

dseeall

This feature enables SEE World debugging for all users.

fto

This feature specifies that ACS authorization is needed to enable foreign token operations (FTO).

The following features remain available for use on presentation of the standard ACS quorum, even if turned off using the ! operator:

  • nvram

  • rtc

  • fto

Setting the quorum of one these features to 0 has the same effect as turning it off using the ! operator.

The passphrase replacement (p) and dseeall features are turned off by default; the other options are turned on by default.

The nonvolatile memory and SEE world debugging options are relevant only if you are using the Secure Execution Engine. If you have bought the CodeSafe Developer Kit, refer to the CodeSafe Developer Guide for more information.
To use extended debugging for the HSM, you must set the dseeall flag.
The dseeall option is designed for testing purposes only. Do not enable this feature on production Security Worlds as it may enable SEE applications to leak security information.

For example, the following features:

m=1, r, !p, nv=2, rtc=1

Create a Security World for which:

  • A single card from the ACS is required to add a new HSM

  • The default number is required to replace an OCS

  • passphrase replacement is not enabled

  • Two cards are required to allocate nonvolatile memory

  • One card is required to set the real-time clock (applies to SEE only).

new-world command-line utility output

If new-world cannot interpret the command line, it displays its usage message and exits.

If you attempt to set a quorum for a feature that you have disabled or if you attempt to set a quorum too high, new-world displays an error and exits.

If the HSM is not in the pre-initialization mode, new-world advises you that you must put the HSM in this mode and waits until you have changed the HSM mode before continuing.

The HSM must be in pre-initialization mode. See Checking and changing the mode on an nShield Edge for more about changing the mode.

If the HSM is in the pre-initialization mode, new-world prompts you for smart cards and passphrases as required.

After you have created a Security World

Store the ACS in a safe place.

If you lose more than N minus K of these Administrator Cards you cannot restore the Security World or lost Operator Cards. For example, if you have a 2/3 ACS and you lose more than one card, you cannot restore the Security World. If you have created an Administrator card set where K = N, then the loss of one card stops you from being able to restore the Security World.

To prevent this situation from occurring, replace lost or damaged cards from the ACS as soon as you discover the loss or damage. For more information, see Replacing the Administrator Card Set.

The security of the keys that you create within this Security World is wholly dependent on the security of these smart cards.

The Security World host data is stored in the directory to which the NFAST_KMLOCAL environment variable points (see Security World Files). The data in this directory is encrypted. You should:

  • Ensure that this directory is backed up regularly.

  • Check the file permissions for this directory.

    • Ensure that the nFast Administrator role, and any user that you want to be able to create Operator Cards or keys, have write permission for this directory.

    • All other valid users must have read permission.

      Installation of Security World Software must be performed by a user with Administrator rights that allow read and write operations, and applications to be started and stopped.

The HSM can now be used to create Operator Cards and keys for the new Security World.

Displaying information about your Security World

To display information about the status of your Security World:

You can also use KeySafe to view a summarized description of the Security World.

Displaying information about a Security World with nfkminfo

To display information about a Security World from the command line, run the command:

nfkminfo -w|--world-info [-r|--repeat] [-p|--preload-client-id]

In this command, the -w|--world-info option specifies that you want to display general information about the Security World. This option is set by default, so you do not need to include it explicitly.

Optionally, the command can also include the following:

Option Description

-r|--repeat

This option repeats the information displayed. There is a pause at the end of each set of information. The information is displayed again when you press Enter.

-p|--preload-client-id

This option displays the preloaded client ID value, if any.

To output a detailed list of Security World information, run nfkminfo with the -w|--world-info option (with or without the other options). For a description of the fields in this list, and more information about using nfkminfo, see nfkminfo: information utility.

The following table maps there flags visible on the front panel when you select 3 Security World mgmt > 3-1 Display World Info to the flags in the output of nfkminfo.

Front panel nfkminfo

admin

k-out-of-n

nCore flags

slotlistflags

NFKM flags

flags

Module slots

nflags

Initialized

Initialised

ForeignTokenOpen

FTO

Displaying information about a Security World with kmfile-dump

To display information about a World from the command line, run the command:

kmfile-dump [<worldfile>]

where <worldfile> is the file storing the World data, usually

If no WorldVersion is received as a result of the command then the World is either version 1 or version 2.

If a WorldVersion of either '2' or '3' is received then the World is version 3.

Adding or restoring an HSM to the Security World

When you have created a Security World, you can add additional HSMs to it. These additional HSMs can be on the same host computer as the original HSM or on any other host. The HSMs may have previously been removed from the same Security World, that is, the Security World can be restored on an HSM by adding the HSM to the Security World again.

You can also restore an HSM to a Security World to continue using existing keys and Operator Cards:

  • After you upgrade the firmware

  • If you replace the HSM.

The additional HSMs can be any nShield HSMs.

To add an HSM to a Security World, you must:

  • Have installed the additional HSM hardware, as described in the Installation Guide.

  • After installing additional HSM hardware and restarting host machine, you must stop and then restart the hardserver as described in Stopping and restarting the client hardserver. This ensures that the added HSM is recognized and accessible.

  • Have a copy of the Security World data on this host. This is the host data written by or new-world when you created the Security World. This data is stored in the local directory within the Key Management Data directory.

    If the Key Management Data directory is not in the default location, ensure that the NFAST_KMDATA environment variable is set with the correct location for your installation.

  • Be logged in to the host computer as see Hardserver start-up settings and server_startup.

  • Have started the HSM in pre-initialization mode.

  • The HSM must be in pre-initialization mode. See Checking and changing the mode on an nShield Edge for more about changing the mode.

  • Possess a sufficient number of cards from the ACS and the appropriate passphrases.

Adding or restoring an HSM to a Security World:

  • Erases the HSM

  • Reads the required number of cards (K) from the ACS so that it can re-create the secret

  • Reads the Security World data from the computer’s hard disk

  • Uses the secret from the ACS to decrypt the Security World key

  • Stores the Security World key in the HSM’s nonvolatile memory

  • Configures the HSM for audit logging if the Security World was created with audit logging selected.

After adding an HSM to a Security World:

  • You cannot access any keys that were protected by a previous Security World that contained that HSM.

  • You have to sync the module file to the clients by one of the following methods:

    • Copy the files manually to the clients.

    • Run rfs-sync -update.

    See Hardserver configuration files.

It is not possible to program an HSM into two separate Security Worlds simultaneously.

Initialization removes any data stored in an HSM’s nonvolatile memory (for example, data for an SEE program or NVRAM-stored keys). To preserve this data, you must back it up before initializing the HSM and restore it after the HSM has been reprogrammed. We provide the nvram-backup utility to enable data stored in nonvolatile memory to be backed up and restored.

In order to continue using existing keys and Operator Cards, you must reprogram the HSM:

  • After you upgrade the firmware

  • If you replace the HSM

  • If you need to add an HSM to an existing Security World.

Adding an HSM to a Security World with new-world

  1. Open a command window and type the command:

    new-world [-l|--program] [-S|--no-remoteshare-cert] [-m|--module=<MODULE>]

    In this command:

    • -l|--program

      This option adds an HSM to an existing Security World (in the Key Management Data directory). If you have multiple HSMs available, you can use the -m|--module=`MODULE option to specify an HSM. If you do not specify an HSM `new-world adds all available HSMs to the Security World.

    • -S|--no-remoteshare-cert

      These options prevent the HSM from becoming a target for remote shares.

    • -m|--module=<MODULE>

      This option specifies the HSM to use (by its ModuleID). If you have multiple HSMs and do not specify an HSM, new-world adds all available HSMs to the existing Security World.

    If new-world cannot find the key-management data, it displays the message:

    new-world: no existing world to load.

    If you intend to initialize the HSM into a new Security World, run new-world with the -i option.

    If the HSM is not in the pre-initialization state, new-world displays an error and exits.

    The HSM must be in pre-initialization mode. See Checking and changing the mode on an nShield Edge for more about changing the mode.

    If the HSM is in the pre-initialization state, new-world prompts you for cards from the Security World’s ACS and to enter their passphrases as required.

  2. After new-world has reprogrammed the HSM, restart the HSM in the operational state.

    The HSM must be in pre-initialization mode. See Checking and changing the mode on an nShield Edge for more about changing the mode.

  3. Store the ACS in a safe place.

If any error occurs (for example, if you do not enter the correct passphrases), the HSM is reset to the factory state. The HSM does not form part of the Security World unless you run new-world again.

Security World migration

The current version of Security World software enables you to create a Security World that fully complies with the NIST Recommendations for the Transitioning of Cryptographic Algorithms and Key Sizes (SP800-131Ar1) or alternatively Common Criteria PP 419 221-5 (common-criteria-cmts) depending on the options selected at World creation. This is called World version 3.

We recommend that where compliance with the specifications above is required, you create a new World and create new keys within that World. However, the software also includes a migrate-world command-line utility that you can use for migrating existing keys into the new World. This is provided as a convenience for customers who require compliance with the specifications, and who need to continue using existing keys.

In the case of a Common Criteria World the specification prohibits the importing of assigned keys. Only general keys can be imported into a common-criteria-cmts World.

Throughout the following sections, the terms Source World refers to the World from which you want to migrate keys, and Destination World refers to the World to which you want to migrate keys.
The utility requires the use of two modules. One module is referred to as the source module. The other module is referred to as the destination module.

Pre-requisites for migrating keys

In order to use the migrate-world utility the following will be needed:

  • Two HSMs. These can be any of the currently supported HSM types and the two HSMs do not need to be of the same type.

  • A quorum of ACS cards for the source World.

  • A quorum of ACS cards for the destination World.

  • Sufficient blank cards to create new OCS cards for any keys that are OCS protected.

Restrictions on migrating keys

The following restrictions apply to the use of migrate-world:

  • The source module must be running firmware version 12.50 or later.

  • The destination module must be running firmware version 12.50 or later.

  • Only recoverable keys can be migrated. If your source keys are non-recoverable, you cannot use the migration utility to migrate keys.

  • Security world software version 13.2 and earlier: The key protection or quorum cannot be changed during migration.

  • Security world software version 13.3 and later: The key protection or quorum can be changed during migration. The new protections must be created in the destination world before migration begins.

  • Replacement cards should be of the same or newer generation than the cards that they replace.

  • The operator running the migrate-world utility must have the access rights to create a privileged connection to the hardserver.

  • The migration tool must have exclusive use of the modules during migration. Do not use them for any other purpose during migration and if either module is an nShield network-attached HSM, do not enter anything via the front panel during migration.

If the destination World is fips-140-level-3, then some keys that were usable in the source World may not be usable in the destination World due to those algorithms or key lengths being restricted. The migration tool might not be able to successfully migrate these keys so they should be removed from the source World before attempting the migration. Any keys of this type that do migrate successfully will be restricted at the point of use.
If the destination World is fips-140-level-3 or common-criteria-cmts the migration tool will automatically remove ExportAsPlain from the ACL of any migrated key during the migration process.
If the destination world does not support audit logging the migration tool will automatically remove LogKeyUsage from the ACL of any migrated key during the migration process.

About the migration utility

You can run the migration utility in the following modes:

  • Plan mode: Returns a list of steps for migration and the required card sets and passphrases but does not migrate any keys.

  • Perform mode: Runs the plan mode prior to presenting the option to proceed and migrate keys according to the plan.

Usage and options

migrate-world [OPTIONS] --src-module=<source_module> --dst-module=<dest_module> --source=<source-kmdata-path> --debug --dst-warrant=<dst-warrant-path> --src-warrant=<src-warrant-path [--plan | --perform] --key-logging
Option Enables you to…​

-k <KEYS>|--keys-at-once=<KEYS>

Migrate no more than this number of keys per ACS loading. This is useful to prevent ACS time-outs if you have a large number of keys to migrate. (0=unlimited, default=0). It is recommended to limit the number of keys to be migrated at any one time to no more than 100.

-h|--help

Obtain information about the options you can use with the utility.

-c <CARDSETS>|--cardsets-at-once=<CARDSETS>

Migrate keys protected by this number of card sets or softcards per ACS loading. This is useful to prevent ACS time-outs if you have a large number of different card sets or softcards to migrate. (0=unlimited, default=0).

--version

View the version number of the utility.

--src-warrant=<src-warrantfile>

Specify the location of the warrant file of the source module.

--src-module=<MODULE>

Specify which module ID to use as the source module.

--source=<SOURCE>

Specify the path to the folder that contains the source World data.

--plan

View the list of steps that will be carried out.

--perform

Migrate keys interactively.

--dst-warrant=<dst-warrantfile>

Specify the location of the warrant file of the destination module.

--dst-module=<ModuleId>

Specify which module ID to use as the destination module.

--debug

Outputs debug messages and stack traces in case of errors. It is recommended to use this only for testing as it will slow down operation and make card timeouts more likely to occur. A large volume of output is produced for each key that is migrated, so it is recommended to migrate a single key at a time when using this option.

--key-logging

This option will enable key usage logging on all migrated keys. If the destination World does not support audit logging the keys will still be migrated but LogKeyUsage logging will not be set in the ACL of the migrated keys.

--src-prots=<list of source protections>

Specify a comma-separated list of OCS or softcard names in the source security world. The keys will be migrated to the corresponding protections specified with --dst-prots.

--dst-prots=<list of destination protections>

Specify a comma-separated list of OCS or softcard names in the destination security world. These will be the target protections for the keys that are protected with methods specified with --src-prots in the source security world.

--prots-config=<PATH>

Specify a configuration file that lists the source and destination protection pairs for migration. The file must contain pairs of tab-separated protection names src_prot dst_prot, one pair per line.
Do not terminate path names in the command parameters with a backslash character. If this is not possible then either terminate with a double backslash or insert a blank space between the backslash and the terminating quotation mark.

Migrating keys

Preparing for migration

Before you begin:

  • Install the latest version of the Security World Software from the installation media. See the Installation Guide for more information.

  • Ensure that the warrant files for the source and destination modules are stored in their default locations. If the warrant files are not at the default location, the --src-warrant and --dst-warrant parameters need to be specified in the migrate-world command.

    • For Solo +, or Solo XC, the default location is

    • For Connect +, Connect XC modules, the default location is

    • For nShield 5s and nShield 5c, you do not need to specify warrant locations because they store their warrants within the module.

  • Copy the source World data to a location defined by the --source=<SOURCE> parameter of the migration tool.

  • If the destination World does not exist already, create a new destination World. For instructions, see Creating a Security World

You must enable all your features on the destination module before migration. Otherwise, the migration will fail.

Migrating keys process

To ensure the security of your keys, we recommend that the migration process is overseen by ACS-holding personnel and the end-to-end migration process is completed continuously, without any breaks in the process. This will also reduce the possibility of your ACS experiencing a time-out.
If the destination World supports audit logging you can choose whether the migrated keys will have key usage logging enabled or not by use of the --key-logging command line switch. If you only wish key usage logging to be enabled on a subset of the keys then you must separate the source keys into two groups and run the migrate-world command separately for each group.

To migrate keys to the destination World:

  1. Run the migration utility in the perform mode with the required options. For information about the usage and options you can use, see About the migration utility.

  2. Ensure that the data for the destination World is in the standard location for World data, derived from one of the following:

    • Either the environment variable NFAST_KMLOCAL or NFAST_KMDATA.

    • The default directory:

  3. If the module is not configured to use the destination World, the utility prompts you to program the module and supply the ACS of the destination World.

  4. The utility guides you through specific steps, prompting you to supply the required card sets and passphrases.

  5. At the end of the migration both the source and destination modules are cleared. If you wish to use the modules then you must reload them with an appropriate Security World.

    The utility will attempt to automatically change the module mode when needed. Should the automatic change of mode fail for any reason, then the utility will prompt you to change the module state to either initialization or operational at various points during the procedure. * The HSM must be in pre-initialization mode. See Checking and changing the mode on an nShield Edge for more about changing the mode.

Verifying the integrity of the migrated keys

To verify the integrity of the migrated keys, run the nfkmverify utility with the following options, as appropriate:

  • If the keys are module-protected, run the utility with one of the following options:

    • -L option, which checks the ACL of a loaded key instead of the generation certificate.

    • -R option, which checks the ACL of a key loaded from a recovery blob.

  • If the keys are protected by cardsets or softcards, run the nfkmverify utility with the -R option in combination with the preload utility.

    Example:

    preload --admin=RE nfkmverify -R -m1 <application> <key-ident>
    Do not use the nfkmverify utility with the default -C option. If you use this option, the utility returns errors because the ACL in the certificate will reflect the old world.
    Note that if the destination World is fips-140-level-3 then some keys that were usable in the source World may not be usable in the destination World due to those algorithms or key lengths being restricted. The migration tool will successfully migrate the keys but they will be restricted at the point of use.

Migrating keys using custom protection pairs

Regular security world migration will create new card sets and softcards in the destination world with the same names as the source protections or it will use existing destination protections if they share a name and type (card set or softcard) with the source protection.

You can specify custom protection pairs if you want to change the name, the quorum, or the properties of the protection. You can also combine multiple source protections of the same type into one destination protection. You cannot diffuse keys from one source protection to multiple destination protections.

The source-destination protection pairs can be selected either as:

  • Two comma-separated lists --src-prots <source protections> and --dst-prots <destination protections>.

  • Tab-separated pairs "source destination", one per line, in a configuration file --prots-config <file path>.

The protections can be referred to by their name, 40-character hash, or "c:name" and "s:name" when a source card set and softcard share a name. The source and destination protection types must match.

The following example shows the two ways of specifying a set of protection pairs and the different ways each protection can be referred to. The example hashes are shortened for readability.

Protection type Source protection to be migrated Target destination protection

card set

ocs 1

ocstarget1

softcard

softcard 1

softcardtarget

card set

name1 (duplicate name)

ocstarget1

softcard

name1 (duplicate name)

softcardtarget

card set

name2 (duplicate name and type) hash: XXXXXXX1

ocstarget1

card set

name2 (duplicate name and type) hash: XXXXXXX2

ocstarget2

By specifying the lists using the --src-prots and --dst-prots options:

migrate-world [OPTIONS] \
--src-prots "ocs 1,softcard 1,c:name1,s:name1,XXXXXXX1,XXXXXXX2" \
--dst-prots "ocstarget1,softcardtarget,ocstarget1,softcardtarget,ocstarget1,ocstarget2"

By using a configuration file specified with the --prots-config option:

migrate-world [OPTIONS] --prots-config=migration.cfg

--- migration.cfg ---
ocs 1    ocstarget1
softcard 1    softcardtarget
c:name1    ocstarget1
s:name1    softcardtarget
XXXXXXX1    ocstarget1
XXXXXXX2    ocstarget2
---------------------

Troubleshooting

If you encounter any errors that are not listed in the following table, contact Support.
Error Explanation Action

There are no keys requiring migration.

Any migrate-able keys found in the source World already exist in the destination World. The migration utility returns this error if:

  • The keys have already been migrated

  • All keys are non-recoverable and therefore cannot be migrated.

None.

Source module must be specified.

Destination module must be specified.

Source and Destination modules must be different.

Module is not usable.

This utility requires you to specify both a source and destination module which must be different modules and both must be usable.

Specify the correct modules.

Source World has indistinguishable cardsets or softcards.

Destination World has indistinguishable keys.

There are irregularities in one of the Worlds, but these irregularities do not affect the migration process.

None.

Destination World has indistinguishable cardsets or softcards.

Source World has indistinguishable keys.

Cannot determine protection of keys.

There are problems with one of the Worlds.

Contact Support.

Source World not recoverable.

The source World is not recoverable and the keys therefore cannot be migrated.

If the source World is not recoverable, you cannot use the migration utility to migrate keys.

Contact Support.

Missing security World at PATH.

Source world must be specified.

The path for the source World is wrong.

There is no World data at the location that was specified when running the migration utility.

Supply the correct path to the source World. If you have supplied the correct path to the directory that contains the source World data, the migration utility has not found a destination World.

Source World is the same as the destination World.

An incorrect path was supplied for the source World data when running the utility.

The destination World data does not exist in the default location defined by the environment variable NFAST_ KMLOCAL or NFAST_KMDATA.

Run the utility with the correct path to the source World data.

Move the source World data to a different location and then copy the destination World data to the default location.

If the default location is defined by an environment variable, configure the variable to point to the location of the destination World, which then becomes the new default location.

Cannot find <NAME> utility, needed by this utility.

<NAME> utility is too old, need at least version <VERSION NUMBER>.

The software installation is partially completed. The path (in the environment variable for the operating system) might be pointing to an old version of the software.

Reinstall the software.

Ensure that the path points to the latest version of the software.

nFast error: TimeLimitExceeded; in response to SetKM…​

The ACS time-out limit has expired.

Restart the key migration process; see Security World migration.

Destination world does not support audit logging.

You have specified the --key-logging option but the destination world does not support audit logging.

None. The keys will be migrated but LogKeyUsage will not be set in the ACL of migrated keys.

Failed to load warrant file <FILE>.

There is a problem reading the warrant file.

Check that your warrant files are in the correct location and have not been edited in any way.

Erasing a module from a Security World

Erasing a module from a Security World deletes from the module all of the secret information that is used to protect your Security World. This returns the module to the factory state. Provided that you still have the ACS and the host data, you can restore the secrets by adding the module to the Security World.

Erasing a module removes any data stored in its nonvolatile memory (for example, data for an SEE program or NVRAM-stored keys). To preserve this data, you must back it up before erasing the module. We provide the nvram-backup utility to enable data stored in nonvolatile memory to be backed up and restored.

In order to erase a module, you must:

You do not need the ACS to erase a module. However, unless you have a valid ACS and the host data for this Security World, you cannot restore the Security World after you have erased it.

After you have erased a module, it is in the same state as when it left Entrust (that is, it has a random module key and a known KNSO).

Erasing a module with new-world

The new-world command-line utility can erase any modules that are in the pre-initialization mode.

To erase modules with the new-world utility, run the command:

new-world [-e|--factory] [-m|--module=<MODULE>]

In the new-world command:

Option Description

-e|--factory

These options restore a module to its factory state.

-m|--module=<MODULE>

These options specify the ModuleID to use. new-world erases only one module at a time. To erase multiple modules, you must run new-world once for every module that you want to erase.

Output

If new-world successfully erased a module, it displays a message that it restored the module to factory state. Otherwise, new-world returns an error message.

Erasing a module with KeySafe

You can erase a module on a server with KeySafe by following these steps:

  1. Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)

  2. Click the World menu button, or select World from the Manage menu. KeySafe takes you to the World Operations panel.

  3. Click the Erase Module button. KeySafe takes you to the Erase Module panel.

  4. Select the module that you want to erase by clicking its listing on the Security world status tree, then click the Commit command button.

    KeySafe erases all secrets from the module, returning it to its factory state.

If you have any keys that were protected by an erased module, you cannot access them unless you restore these secrets. You cannot restore these secrets unless you have the appropriate ACS.

Erasing a module with initunit

The initunit command-line utility erases any modules that are in the pre-initialization state.

To erase modules with the initunit utility, run the command:

initunit [-m|--module=<MODULE>] [-s|--strong-kml]

In the initunit command, --module=<MODULE> specifies the ID of the module you want to erase. If you do not specify this option, all modules in the pre-initialization state are erased. --strong-kml specifies that the module generates an AES (SP800-131A) module signing key, rather than the default key.

The --disablepkcs1pad option will only work on SP800-131A Security Worlds.

Output

If initunit is successful, for each module that is in the pre-initialization state, it returns a message similar to this:

 Initialising Unit
># Setting dummy HKNSO Module Key Info:
 HKNSO
>################### HKM
>###################

Otherwise, initunit returns an error message.

Deleting a Security World

You can remove an existing Security World and replace it with a new one if, for example, you believe that your existing Security World has been compromised. However:

  • You are not able to access any keys that you previously used in a deleted Security World

  • It is recommended that you reformat any nShield Remote Administration Cards that were used as Operator Cards within this Security World before you delete it. For more information about reformatting (or erasing) Operator Cards, see Erasing cards and softcards.

Except for nShield Remote Administration Cards, if you do not reformat the smart cards used as Operator Cards before you delete your Security World, you must throw them away because they cannot be used, erased, or reformatted without the old Security World key.
You can, and should, reuse the smart cards from a deleted Security World’s ACS. If you do not reuse or destroy these cards, then an attacker with these smart cards, a copy of your data (for example, a weekly backup) and access to any nShield key management HSM can access your old keys.

To delete an existing Security World:

  1. Remove all the HSMs from the Security World.

  2. Delete the Security World data files, see Location of Security World files.

    There may be copies of the Security World data archive saved on your backup media. If you have not reused or destroyed the old ACS, an attacker in possession of these cards could access your old keys using this backup media.
    If audit logging was enabled for the Security World then audit logs can still be verified provided that the audit log data is maintained as this contains all the information needed to verify the logs. For further information see Audit Logging.