migrate-world

Migrate existing keys to a destination Security World.

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

Prerequisites for using migrate-world

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.

  • For PCIe HSMs: Remote mode switching must be enabled on both HSMs used for the migration.

  • For network-attached HSMs: Remote mode switching must be enabled on both HSMs used for the migration. See enable_remote_mode in the server_settings section or the Top-level menu chapter of the HSM Install Guide.

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

Option Description

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

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

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

--dst-module=<ModuleId>

Specifies which module ID to use as the destination module.

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

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

--dst-warrant=<dst-warrantfile>

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

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

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

--key-logging

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

--perform

Migrates keys interactively.

--plan

Displays the steps that will be carried out.

--prots-config=<PATH>

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

--source=<SOURCE>

Specifies the path to the folder that contains the source world data.

--src-module=<MODULE>

Specifies which module ID to use as the source module.

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

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

--src-warrant=<src-warrantfile>

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

Help options

-h, --help

Displays help for migrate-world.

-u, --usage

Displays a brief usage summary for migrate-world.

-v, --version

Displays the version number of the Security World Software that deploys migrate-world.
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.

Restrictions on using migrate-keys

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

  • You can change some, but not all, security world properties during migration:

    Property Up to 13.3 13.4 and later

    Key protection method
    whether softcard or OCS is used

    Fixed

    Fixed

    Key protection name
    softcard name or cardset name

    Fixed

    Editable

    Quorum

    Editable

    Editable

    If the name or quorum is to be changed, you must create the softcard or OCS 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 in the correct location.

    The migration process directly downloads the warrants from the module for the nShield 5s and nShield 5c HSMs. You do not need to take any action.

    For pre-nShield5 HSMs:

    • If one or both of the modules have a KLF warrant, you must request an upgrade to a KLF2 warrant from nshield.support@entrust.com before you start the migration.

    • For Solo + and Solo XC, the default location is NFAST_KMDATA/warrants/ (Linux) or NFAST_KMDATA\warrants\ (Windows).

    • For Connect + and Connect XC, the default location is NFAST_KMDATA/hsm-<ESN>/warrants/ (Linux) or NFAST_KMDATA\hsm-<ESN>\warrants\ (Windows).

    • After adding or upgrading to a KLF2 warrant, you must reboot the HSM before the warrant file will appear in the warrants directory.

    See Warrant Management.

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

migrate-world to migrate 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
---------------------

Troubleshoot migrate-world

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.

migrate-world 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 [SecurityWorldMigration].

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.