Migration to Next Generation Hardware Appliance

The migration from the Legacy Hardware Appliance to the Next Generation Hardware Appliance is performed by importing/restoring a backup.

Before proceeding, ensure that all prerequisites have been thoroughly reviewed and met to avoid potential issues, see Prerequisites.

General information

This section provides guidance for migrating from the Legacy Hardware Appliance to the Next Generation Hardware Appliance.

FIPS Mode

The migration of the Legacy Hardware Appliance in FIPS mode to Next Generation Hardware Appliance is not supported.

Number of PKCS#11 Slots limited

The keys required by the Legacy Hardware Appliance and your infrastructure are organized in slots. It is quite possible that more slots are used in the current version than can be migrated, i.e. that the number of slots in use is greater than the number of exportable slots.
To check your current list of slots:

1. Open the HSM tab in WebConf.

2. Click the second sub-tab PKCS#11 Slots.

3. A list of all PKCS#11 Slot Configuration is displayed there.
   The number of slots permitted on the Legacy Hardware Appliance is:

1 for SignServer (only Slot ID 1)

If the process is nevertheless continued with surplus slots, a warning appears in WebConf.

Slot Authentication Codes

Slot Authentication Codes can be

• Manually Specified Slot Authentication Codes, or

• Automatically Generated Slot Authentication Codes

Manually specified Slot Authentication Codes that have less than 8 characters

If your Legacy Hardware Appliance happens to have slot authentication codes with less than 8 characters, the restore process will fail on the Next Generation Hardware Appliance.

In this case, an error message appears. This message looks as follows:

Error B083001D

CryptoServer module CMDS,

Command scheduler bad user token (key or password)

To successfully complete the restore process, the slot authentication code on the Legacy Hardware Appliance must be corrected.

1. Open the HSM tab in WebConf.

2. Click the second sub-tab PKCS#11 Slots.

3. The Authentication code column in the table shows how the code was generated for each slot:

   1. Manually specified or

   2. Generated.

4. Click Change to open the sub menu for modifications.

5. Change the slot authentication code to at least 8 characters and Save your settings.

Now restart the Export of the backup and restore it in the Hardware Appliance 4.0.0 again.

Automatically Generated Slot Authentication Codes

During the Export that contains slots that have an Automatically Generated Slot Authentication Code, the Domain Master Secret (DMS) is set as a password.
This is necessary in order to be able to change the slot authentication codes later in the Next Generation Hardware Appliance.
The length of the DMS is monitored when the migration backup from Legacy Hardware Appliance to Next Generation Hardware Appliance is performed.

The Export button is deactivated if the following conditions are met:

• At least one slot has an Automatically Generated Slot Authentication Code.

• DMS is shorter than 8 characters.

In this case, all slots with automatically generated slot authentication codes must be changed to manually specified slot authentication codes.

To change the codes:

1. Open the HSM tab in WebConf.

2. Click the second sub-tab PKCS#11 Slots.

3. The Authentication code column of the table shows how the code was generated for each slot.
   Manually specified or Generated.

4. Click Change to open the sub menu for modifications.

5. Change from Generated to Manually specified and enter the slot authentication code with at least 8 characters.

6. Save your settings.

Now restart the Export of the backup and restore it in the Next Generation Hardware Appliance again.

Once all slots have manually specified slot authentication codes, the length of the DMS will not matter, and the migration backup can be exported.

Certificate Chains

The new Next Generation Hardware Appliance only supports entire certificate chains for user authentication (Trusted CA).
The Legacy Hardware Appliance excepted as well partial certificate chains.
In the rare case that only incomplete certificate chains are available, i.e. there are no entries under Trusted CA after the restore, an OpenID Connect (OIDC) user is created.

• the OIDC user is named migration

• the password is the DMS

Backup Configurations

All existing configurations and backup schedules cannot be exported.

These settings need to be reconfigured on the Next Generation Hardware Appliance.

Simple Network Management Protocol (SNMP) Configuration

The SNMP configuration is not migrated and must be reconfigured if it was previously used.
(The Open IDs (OIDs) will change anyway.)

Info for Tier 3 Certification Authorities (CA) Users

Only 2 Tier Certification Authorities will be migrated to the Next Generation Hardware Appliance.

The third Tier must be added manually in the Next Generation Hardware Appliance Webconf after a successful restore.
It is important to increase the TLS Verification Depth before uploading the third Tier to the Webconf.
If this step is not carried out, the Webconf will show an error message.

Internal OCSP

If an internal OCSP has been set in the Legacy Hardware Appliance please note that this configuration will be omitted during the migration process to the Next Generation Hardware Appliance.

Prerequisites

Upgrade

To ensure the success of the migration, it is essential that the Legacy Hardware Appliance is updated to the latest version.
All instructions in the Release and Upgrade Notes must be observed.

The Migrate to NextGen sub menu only appears in the WebConf Backup menu once the appliance has been successfully updated.

In addition, it is important to consider the list of General information to ensure that all necessary changes and adjustments have been made before starting the Migration.

Migration

Migrate to the Next Generation Hardware Appliance (NextGen)

Create a full migration Export in WebConf to be able to export your data.

In WebConf click the Backup tab.

Use the sub-tab Migrate to NextGen.
You have the following options:

• Application:
  choose between
  EJBCA or SignServer

• Device:
  Network File System (NFS)

• Destination Host:
  Set the IPv4 address of the DNS hostname. The address must point to a record in the configured DNS that stores at least one IPv4 address.

• Destination Path:
  Set the base path for the NFS share to be used. This is always an absolute path.

• Notes:
  Notes on the export can be entered in this field.

• Click Export Now.
  Select Export Now to start the export to the specified location in the background.

• To check if the backup is complete, go back to the Backup > Migrate to NextGen sub tab at a later time. A backup on an empty or freshly installed system is usually completed within minutes.

• To verify the backups have been saved, click Show Files.
  Select Show Files to view the files.

If settings do not meet the requirements of Next Generation Hardware Appliance, a corresponding error message appears in Webconf describing why the export could not be executed and indicating the problem.

General errors in the export process are reported with an error message in Webconf.

Examples:

• A backup error during DB streaming is reported with a special message about the DB backup.

• Backup errors during HSM backup are reported with a special message about the HSM backup.

• An error during backup when a file is missing is reported with a special message stating that the file was not found.

To continue please refer to Restoring a Migration Backup in the Next Generation Hardware Appliance Documentation.