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:
-
The Installation Guide for more about installing the module and software.
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
new-world
command line utility
See Creating a Security World using new-world.
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 thekmdata
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:
-
If
NFAST_KMLOCAL
is set, use that. -
Otherwise, if
NFAST_KMDATA
is set, use${NFAST_KMDATA}/local
on Linux,%NFAST_KMDATA%\local
on Windows. -
Otherwise, if
NFAST_HOME
is set, use${NFAST_HOME}/kmdata/local
on Linux,%NFAST_HOME%\kmdata\local
on Windows. -
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 |
(for each module in the Security World) |
Load a Security World |
creates or modifies |
(for each module in the Security World) |
Replace an ACS |
modifies |
|
Create an OCS |
creates |
|
Create a softcard |
creates |
|
Generate a key |
creates |
|
Recover a key |
modifies |
|
-
<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
%NFAST_KMDATA%\local
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.
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
%NFAST_KMDATA%\local
directory is not overwritten but renamed
%NFAST_KMDATA%\local_N
(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
%NFAST_KMDATA%\local_N
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 5s module for more about changing the mode.
-
You must be logged in to the host computer as a user who is permitted to create privileged connections or as a user in the group
nfast
. For more information, see server_settings.
-
You must have set the
NFAST_HOME
environment variable.This variable is set by default during product software installation.
-
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 | ||||||
---|---|---|---|---|---|---|---|
|
This option creates a new Security World, replacing any existing
|
||||||
|
This option erases an HSM, restoring it to factory state. |
||||||
|
This option prevents making the HSM from becoming a target for remote shares. |
||||||
|
If you have not specified a mode parameter you can use the |
||||||
|
Omitting this option will create a default Security World compliant with FIPS 140 Level 2. |
||||||
|
This option disables the ability to recovery or replace OCSs and softcard (which is otherwise enabled by default). This is equivalent to setting By default,
|
||||||
|
This option specifies the Cipher suite and type of key that is used to protect the new Security World. |
||||||
|
This option allows you to specify the time-out ( |
||||||
|
This option specifies the module to use (by its |
||||||
|
In this option,
This option only takes effect if you are creating a new Security World. |
||||||
|
This option instructs |
||||||
|
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. |
||||||
|
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:
However, the passphrase can still be used. Example:
If |
||||||
|
This option enables passphrases to have at least one uppercase, lowercase, number, and symbol. If the |
||||||
|
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.
Audit logging is automatically enabled when the Security World is created in |
||||||
|
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 |
||||||
|
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 |
---|---|
|
This feature makes it possible to add new HSMs into the Security World. This feature cannot be disabled. |
|
This feature enables OCS and softcard replacement; see Replacing Operator Card Sets. |
|
This feature enables passphrase replacement; see passphrase replacement and Changing card and softcard passphrase. |
|
This feature specifies that ACS authorization is needed to enable nonvolatile memory (NVRAM) allocation. |
|
This feature specifies that ACS authorization is needed to set the real-time clock (RTC), see Real-time clock (RTC) options. |
|
This feature specifies that that ACS authorization is needed to enable SEE World debugging. |
|
This feature enables SEE World debugging for |
|
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 5s module 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:
-
Run the
nfkminfo
command-line utility. See Displaying information about a Security World with nfkminfo. -
Run the
kmfile-dump
command-line utility. See Displaying information about a Security World with kmfile-dump.
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 |
---|---|
|
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. |
|
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 |
---|---|
|
|
|
|
|
|
Module |
|
|
|
|
|
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
%NFAST_KMDATA%\local\world
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 Keysafe, the nShield HSM CSP wizard, or
new-world
when you created the Security World. This data is stored in thelocal
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 a user who is permitted to create privileged connections; 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 5s module 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
.
-
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 the CSP or CNG wizard
To add an HSM to an existing Security World:
-
Ensure the HSM is in initialization mode and run the wizard by double-clicking its shortcut in the Windows Start menu: Start > Entrust nShield Security World.
-
Click the Next button.
The wizard allows you to configure HSM Pool mode for CAPI/CNG.
-
Click the Next button.
If the wizard finds an existing Security World, it prompts you to specify whether you want to use the existing Security World or create a new Security World.
If the wizard displays any other windows:
-
Cancel the operation.
-
Check that you have correctly set the environment variable
NFAST_KMDATA
. -
Copy the
local
sub-directory from the Key Management Data of another computer in the same Security World or from a backup tape of this computer to the Key Management Data directory of this computer. -
Run the wizard again.
-
-
Ensure that the Use the existing security world option is selected, and click the Next button.
You can then proceed to add HSMs in the same manner that you add multiple HSMs when you create a Security World.
Adding an HSM to a Security World with new-world
-
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 5s module 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. -
-
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 5s module for more about changing the mode.
-
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.
-
Remote mode switching must be enabled on both HSMs used for the migration.
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 source and destination modules must both have KLF2 warrants.
nShield Connect and nShield 5c HSMs have a pre-installed KLF2 warrant file in:
Linux
NFAST_KMDATA/hsm-<esn>/warrants/<esn>
.Windows:
NFAST_KMDATA\hsm-<esn>\warrants\<esn>
If one or both of the modules are Solo XC and have a KLF warrant you should request an upgrade to a KLF2 warrant before starting migration, see Warrant Management for nShield 5s.
-
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… |
---|---|
|
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. |
|
Obtain information about the options you can use with the utility. |
|
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). |
|
View the version number of the utility. |
|
Specify the location of the warrant file of the source module. |
|
Specify which module ID to use as the source module. |
|
Specify the path to the folder that contains the source World data. |
|
View the list of steps that will be carried out. |
|
Migrate keys interactively. |
|
Specify the location of the warrant file of the destination module. |
|
Specify which module ID to use as the destination module. |
|
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. |
|
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. |
|
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 |
|
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 |
|
Specify a configuration file that lists the source and destination protection pairs for migration.
The file must contain pairs of tab-separated protection names |
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 themigrate-world
command.-
For Solo +, or Solo XC, the default location is
NFAST_KMDATA\warrants\
. -
For Connect +, Connect XC modules, the default location is
NFAST_KMDATA\hsm-<ESN>\warrants\
. -
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:
-
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.
-
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
orNFAST_KMDATA
. -
The default directory:
C:\ProgramData\Key Management Data\local
, orC:\Documents and Settings\All Users\Application Data\nCipher\Key Management Data\local
, as appropriate.
-
-
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.
-
The utility guides you through specific steps, prompting you to supply the required card sets and passphrases.
-
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 5s module 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 |
|
|
softcard |
|
|
card set |
|
|
softcard |
|
|
card set |
|
|
card set |
|
|
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:
|
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 |
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 |
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. |
Migrating KMDATA
To move KMDATA from the default location of C:\ProgramData\nCipher
:
-
Open a command prompt window as an administrator.
-
Use
Xcopy
with the following parameters to copy the default folder to a new location:Xcopy C:\ProgramData\nCipher <Destination> /e /v /o /i
-
Enter the new location for the following environment variables:
-
In the Windows Control Panel, navigate to Control Panel > System and Security > System > Advanced system settings.
-
In the Advanced tab, select Environment Variables.
-
Update the following system variables:
-
NFAST_CERTDIR:
<path\to\new\folder>\Feature Certificates
-
NFAST_KMDATA:
<path\to\new\folder>\Key Management Data
-
NFAST_LOGDIR:
<path\to\new\folder>\Log Files
-
-
If your Security World client is on or above v12.70.4, add the following environment variable in the same section:
-
NFAST_KNETIDIR:
<path\to\new\folder>\hardserver.d
-
-
-
In the Services tool, restart the nFast Server process.
-
After the service restarts, run the following command to check the migration was successful:
anonkneti -m 127.0.0.1
-
After confirming that the migration was successful, delete
C:\ProgramData\nCipher
.
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:
-
Be logged into your computer as a user who is permitted to create privileged connections.
-
Have started the module in the pre-initialization mode.
-
The HSM must be in pre-initialization mode. See Checking and changing the mode on an nShield 5s module for more about changing the mode.
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 K
NSO).
If you are physically removing the module from the machine where it is installed, run hsmadmin enroll after removing the module.
This refreshes the list of nShield 5s modules currently installed on the machine.
|
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 |
---|---|
|
These options restore a module to its factory state. |
|
These options specify the |
Erasing a module with KeySafe
You can erase a module on a server with KeySafe by following these steps:
-
Start KeySafe. (For an introduction to KeySafe and information on starting the software, see Using KeySafe.)
-
Click the World menu button, or select World from the Manage menu. KeySafe takes you to the World Operations panel.
-
Click the Erase Module button. KeySafe takes you to the Erase Module panel.
-
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.
|
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:
-
Remove all the HSMs from the Security World.
-
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.