Migration to Hardware Appliance Version 4

The migration from Hardware Appliance Version 3.14.1 to the new Hardware Appliance Version 4.0.0 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 Hardware Appliance Version 3.x to the new Hardware Appliance Version 4.0.0.

FIPS Mode

The migration of the Hardware Appliance in FIPS mode to new Hardware Appliance Version 4.0.0 is not supported.

Number of PKCS#11 Slots limited

The keys required by the Hardware Appliance and your infrastructure are organized in slots. It is quite possible that more slots are in use on the current version than can be migrated.
It can happen that the number of available slots is greater than the number that can be exported.
To check your current list of slots:

Open the HSM tab in WebConf.
Click the second sub-tab PKCS#11 Slots.
There a list with all PKCS#11 Slot Configuration is shown.
The number of slots permitted on the Hardware Appliance Version 3.14.0 is:

10 for EJBCA (Slot ID 0 to Slot 9)

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

The number of slots exceeds the limit that can be restored to Hardware Appliance 4.0.0. Restoring to EJBCA accepts up to 10 slots. The remaining slots will be discarded.

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 Hardware Appliance happens to have slot authentication codes with less than 8 characters,
the restore process will fail on the new Hardware Appliance Version 4.0.0.

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 Hardware Appliance Version 3.14.1 must be corrected.

Open the HSM tab in WebConf.
Click the second sub-tab PKCS#11 Slots.
The Authentication code column of the table shows how the code was generated for each slot.
Manually specified or Generated.
Click Change to open the sub menu for modifications.
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 new Hardware Appliance 4.0.0.
The length of the DMS is monitored when the migration backup from Hardware Appliance 3.14.1 to Hardware Appliance Version 4.0.0 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:

Open the HSM tab in WebConf.
Click the second sub-tab PKCS#11 Slots.
The Authentication code column of the table shows how the code was generated for each slot.
Manually specified or Generated.
Click Change to open the sub menu for modifications.
Change from Generated to Manually specified and enter the slot authentication code with at least 8 characters.
Save your settings.

Now restart the Export of the backup and restore it in the Hardware Appliance 4.0.0 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 Hardware Appliance Version 4.0.0 only supports entire certificate chains for user authentication (Trusted CA).
The Hardware Appliance Version 3.14.1 excepted as well partial certificate chains.
In the rare case that there are only incomplete certificate chains, 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 Hardware Appliance Version 4.0.0.

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 Hardware Appliance Version 4.0.0.

The third Tier must be added manually in the Hardware Appliance Version 4.0.0 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.

Prerequisites

Upgrade

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

Only after the appliance has been successfully updated to Version 3.14.1 does the Export for Version 4.0.0 sub-menu appear in the WebConf Backup menu.

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

Export for Version 4.0.0 from Hardware Appliance Version 3.14.1

Create a Full Migration Backup in WebConf to be able to export your data.

In WebConf click the Backup tab.

Use the sub-tab Export for Version 4.0.0.
You have the following options:

Application:
activate EJBCA

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 backup to the specified location in the background.
To check if the backup is complete, go back to the Backup > Export for Version 4.0.0 sub tab at a later time. A backup on an empty or freshly installed system is usually done 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 Hardware Appliance Version 4.0.0, a corresponding error message appears in WebConf describing why the export could not be executed and pointing to the issue.

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.

The appliance must now be rebooted to complete the migration.