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

  • (nShield Solo, Solo XC, and Connect) Remote mode switching must be enabled on both HSMs used for the migration.
    See enable_remote_mode in the server_settings section or Top-level menu

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.

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

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

  • 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 NFAST_KMDATA/warrants/ (Linux) or NFAST_KMDATA\warrants\ (Windows).

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

    • 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 Create a new 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:

      • (Linux) /opt/nfast/kmdata/local/

      • (Windows) C:\ProgramData\Key Management Data\local, or C:\Documents and Settings\All Users\Application Data\nCipher\Key Management Data\local, as appropriate.

  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.

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

Migrating KMDATA (Windows)

To move KMDATA from the default location of C:\ProgramData\nCipher:

  1. Open a command prompt window as an administrator.

  2. Use Xcopy with the following parameters to copy the default folder to a new location:

    Xcopy C:\ProgramData\nCipher <Destination> /e /v /o /i

  3. Enter the new location for the following environment variables:

    1. In the Windows Control Panel, navigate to Control Panel > System and Security > System > Advanced system settings.

    2. In the Advanced tab, select Environment Variables.

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

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

  4. In the Services tool, restart the nFast Server process.

  5. After the service restarts, run the following command to check the migration was successful:

    anonkneti -m 127.0.0.1

  6. After confirming that the migration was successful, delete C:\ProgramData\nCipher.