Renew or Migrate the Cryptography Keys

Important: To renew the cryptography keys using the following procedures, your system must be updated with the latest ActivID AS 8.5 hot fix.

As ftadmin, use the migrationKeySetTool.sh script to renew the key set or migrate to an HSM slot.

Command usage is:

Copy 
<ACTIVID_HOME>/ActivID_AS/bin/migrationKeySetTool.sh [-d <domain1,domain2,...> | -m | -c <domain1,domain2,...> | -k <domain1,domain2,...> ]

Where the options are:

  • -d – renew the key set with a service interruption

    You must specify the domains.

    This operation requires a service interruption as the database is encrypted in a single operation that does not timeout.

    Note: It is strongly recommended using the silent key set renewal option instead to minimize the service interruption.
  • -m – migrate to a specific external HSM slot

    The migration concerns all existing domains.

    This operation requires a service interruption as the database is encrypted in a single operation that does not timeout.

  • -c - modify the key configuration manually

    You must specify the domains.

  • -k - renew the key set silently without a service interruption

    You must specify the domains.

    This operation does not require a service interruption as the database is encrypted progressively, where each operation will timeout after 120 minutes (default).

Important:  Shared Key Set vs Domain-Specific Key Set

You can switch from a shared key set to a domain-specific key set.

If you want to move from shared keys to domain-specific keys (and vice versa), you must change the index level of the key set. For example, if you are currently using shared keys with index 1, you must use domain-specific keys with index 2.

Prerequisites:  For all the key set renewal/migration operations:
  • As Audit records will be deleted during the operation, you must back up the database and verify that the latest audit records have been archived.
  • You must know the password(s) for the security domain(s) as you will be prompted for them during the process.
  • The expected key set is available. If necessary, create the new key set.

Renew the Key Set

In order to use a new set of keys, you must define the new key level in the cryptographic configuration.

This tool allows you to switch to the shared keys index immediately following that currently used, or switch to a defined domain keys index.

You can renew the key set in a single operation (with a service interruption) or progressively (without a service interruption).

Renew the Keys with a Service Interruption

  1. Stop the ActivID AS services.
  2. As ftadmin, run the following command to update the cryptographic configuration (for example, for the ONLINEBANK and ENTERPRISE domains):
Copy 
su ftadmin -c "<ACTIVID_HOME>/ActivID_AS/bin/migrationKeySetTool.sh  -d ONLINEBANK,ENTERPRISE"
 
Working in SOFT mode.
 
Validate the specified domains:
--> Keys will be migrated for ONLINEBANK
--> Keys will be migrated for ENTERPRISE
 
You are about to migrate to a new key set.
This is a very sensitive operation and might take a long time.
The ActivlD applications will be unavailable during the entire process.
 
Important: All ActivlD AS services MUST be stopped.
In addition, as the entire database will be modified, make sure that you have created a backup.
Make sure that the new set of keys is available and accessible before you begin.
 
If an error occurs during the migration, please refer to the indicated log file.
If an error does occur, you might be required to restore the backup of the database to return to the functional configuration.
 
Do you really want to migrate the key set (y/n)? [n]: y
  1. Enter y to proceed.
Copy 
Security Domain settings:
     Domain: ‘ONLINEBANK’
     Password:
          Checking connection ... connection successful
     Domain: ‘ENTERPRISE’
     Password:
          Checking connection ... connection successful
Do you confirm the Security Domain settings (y/n)? [n]: y
  1. When prompted, enter the password(s) for the security domain(s) and then enter y to confirm the settings.
    2. Note: If the password for one or more domains is incorrect, an error message is displayed.
    Copy
    Security Domain settings:
         Domain: ‘ONLINEBANK’
         Password:
              Checking connection ... connection successful
         Domain: ‘ENTERPRISE’
         Password:
              Checking connection ... connection failed
    Connection failed. Do you want to retry or exit (r/e)? [r]: r

    Enter r to retry, and then enter the correct password(s).

    If you enter e to exit, the operation is canceled.

Copy 
Current configuration for targeted domains:
Using specific shared keys index value 1 for domain ONLINEBANK
Do you want to switch to domain keys for ONLINEBANK (y/n)? [n]:
Using specific shared keys index value 1 for domain ENTERPRISE
Do you want to switch to domain keys for ENTERPRISE (y/n)? [n]:

  1. By default, the configuration is updated to the next level of the shared key set (in this example, index 2).

    • If you want to use the next level of the shared key set, press Enter for each domain.
    • If you want to switch to domain-specific key set, enter y.
      • Copy 
      Current configuration for targeted domains:
      Using specific shared keys index value 1 for domain ONLINEBANK
      Do you want to switch to specific domain keys for ONLINEBANK (y/n)? [n]: y
       
      Please enter next specific domain key set for ONLINEBANK [1]:
Copy 
Please make sure the following listed key set is available.
 
Required keys to migrate domain ONLINEBANK:
         HID-IA-4T.AUDIT.ONLINEBANK.2
         HID-IA-4T.DSIGN.ONLINEBANK.2
         HID-IA-4T.CREDS.ONLINEBANK.2
         HID-IA-4T.SYS.ONLINEBANK.2
         HID-IA-4T.SESSION.ONLINEBANK.2
 
Required keys to migrate domain ENTERPRISE:
         HID-IA-4T.AUDIT.ENTERPRISE.2
         HID-IA-4T.DSIGN.ENTERPRISE.2
         HID-IA-4T.CREDS.ENTERPRISE.2
         HID-IA-4T.SYS.ENTERPRISE.2
         HID-IA-4T.SESSION.ENTERPRISE.2
 
Please confirm you really want to migrate the keys (y/n)? [n]: y
  1. Enter y to confirm the operation.

    2. The script then re-encrypts and re-signs the data and updates the signatures of the database tables.

Renew the Keys Silently (without a Service Interruption)

To minimize the service interruption, you can silently re-encrypt the database with the new keys using the progressive renewal option.

As this operation times out after 120 minutes, you can repeat the encryption of the database until all the existing records are encrypted with the new keys.

Set the Key Set Configuration

The renewal operation requires that the current key set configuration is correct.

  1. As ftadmin, run the following command to check/update the cryptographic configuration (for example, for the ONLINEBANK domain):
Copy 
su ftadmin -c "<ACTIVID_HOME>/ActivID_AS/bin/migrationKeySetTool.sh -c ONLINEBANK"

Working in HSM mode.
 
Validate the specified domains:
--> Keys will be migrated for ONLINEBANK
 
 
You are about to manually update the keys configuration.
 
Important: ActivID AS services needs to be restarted to use new configuration.
In addition, as the database will be modified, make sure that you have created a backup.
Make sure that the new set of keys is available and accessible before you begin.
 
If an error occurs during the migration, please refer to the indicated log file.
 
Do you really want to manually update keys configuration (y/n)? [n]: y
  1. Enter y to proceed.
Copy 
Current configuration for targeted domains:
Be careful: you are going to set manually the keys index to use for each domain.
You will be asked later to confirm or not the new configuration
Domain ONLINEBANK:
CURRENT_INDEX_STANDARD: 1
CURRENT_INDEX_DOMAIN: 0
Do you want to use domain keys for ONLINEBANK (y/n)? [n]:
Please enter next key set index for ONLINEBANK [1]: 2

By default, the configuration is updated to the next level of the shared key set (in this example, index 2).

  • If you want to use the next level of the shared key set, press Enter for each domain.
  • If you want to switch to domain-specific key set, enter y.
    • Copy 
    Current configuration for targeted domains:
    Using specific shared keys index value 1 for domain ONLINEBANK
    Do you want to switch to specific domain keys for ONLINEBANK (y/n)? [n]: y
     
    Please enter next specific domain key set for ONLINEBANK [1]:

In this example, ONLINEBANK should be encrypted with the new set of shared keys (index level 2).

Copy 
Reset map values
checkKeyStore returns 0
Soft keystore mode.
Reset map values
checkKeyStore returns 0
 
Keys checking successfully ended.
keystatus 0
 
Please make sure the following listed key set is available.
 
Required keys to migrate domain ONLINEBANK:
         HID-IA-4T.AUDIT.2
         HID-IA-4T.DSIGN.2
         HID-IA-4T.CREDS.2
         HID-IA-4T.SYS.2
         HID-IA-4T.SESSION.2
 
New configuration has been set up. Please restart the server to use the new cryptographic configuration.
  1. Restart ActivID AS to use the new key set configuration.
Important: Before starting the re-encryption of the database, you must repeat the above steps on each node in your deployment to apply the same key configuration.

Re-Encrypt the Database with the New Key Set

Once the current configuration is validated and loaded by the server, you can start the progressive re-encryption of the database records.

Note: The following steps should only be applied on a single node to minimize the impact on the service.
  1. As ftadmin, run the following command to start the progressive encryption of the database for the ONLINEBANK domain:
Copy 
su ftadmin -c "<ACTIVID_HOME>/ActivID_AS/bin/migrationKeySetTool.sh -k ONLINEBANK"

Working in HSM mode.
 
Validate the specified domains:
--> Keys will be migrated for ONLINEBANK
 
 
You are about to migrate in progressive mode.
This is a very sensitive operation and might take a long time.
The ActivID applications will stay available during the entire process.
 
If an error occurs during the migration, please refer to the indicated log file.
 
Do you really want to migrate to current keys set in progressive mode (y/n)? [n]: y
  1. Enter y to proceed.
Copy 
Security Domain settings:
     Domain: 'ONLINEBANK'
     Password:
         Checking connection ... connection successful
  1. When prompted, enter the password(s) for the security domain(s) and then enter y to confirm the settings.
Note: If the password for one or more domains is incorrect, an error message is displayed.
Copy
Security Domain settings:
     Domain: ‘ONLINEBANK’
     Password:
          Checking connection ... connection failed
Connection failed. Do you want to retry or exit (r/e)? [r]: r

Enter r to retry, and then enter the correct password(s).

If you enter e to exit, the operation is canceled.

Copy 
Current configuration for targeted domains:
Configuration for domain ONLINEBANK
Current standard index: 2
Current domain index: 0
 
Please make sure the following listed key set is available.
 
Required keys to migrate domain ONLINEBANK:
         HID-IA-4T.AUDIT.2
         HID-IA-4T.DSIGN.2
         HID-IA-4T.CREDS.2
         HID-IA-4T.SYS.2
         HID-IA-4T.SESSION.2
 
Migrating HSM keys (renewal with expiration time case)...
Migrating keys (renewal with expiration time case) in mode HSM
 
You are working in mode HSM.
You are ready to start migrating the database.
You want to migrate only records not already encrypted/signed by the current key configuration and limit this operation to 120 minute(s).
Please confirm you want to perform the migration (y/n)? [n]: y
  1. Enter y to confirm the operation.
Copy 
Starting migration (renewal with expiration time set to 120 minutes case)
Keys have been migrated with success.
  1. Repeat the encryption operation (the -k option) until all the records in the database are using the new keys.

    Confirm the status by checking the configuration - the encryption for each table must be 100%.

Migrate from SOFT Mode to HSM Mode

To migrate to HSM cryptography, you can specify the required slot in the cryptographic configuration. The key level index will be reset to 1 in the cryptographic configuration.

The script will get the targeted slot, check if the slot is PIN protected and, if so, prompt for the PIN, and then check the keys and migrate.

The following example illustrates how to migrate from Software Cryptographic Mode to slot 0 of an External HSM.

  1. Stop the ActivID AS services.
  2. As ftadmin, run the following command to migrate the cryptographic configuration.
Copy 
su ftadmin -c "<ACTIVID_HOME>/ActivID_AS/bin/migrationKeySetTool.sh -m"
 
Working in SOFT mode.
 
Validate the specified domains:
--> Keys will be migrated for ONLINEBANK
 
You are about to migrate to a new key set.
This is a very sensitive operation and might take a long time.
The ActivlD applications will be unavailable during the entire process.
 
Important: All ActivlD AS services MUST be stopped.
In addition, as the entire database will be modified, make sure that you have created a backup.
Make sure that the new set of keys is available and accessible before you begin.
 
If an error occurs during the migration, please refer to the indicated log file.
If an error does occur, you might be required to restore the backup of the database to return to the functional configuration.
 
Do you really want to migrate the key set (y/n)? [n]: y
  1. Enter y to proceed.
Copy 
Security Domain settings:
     Domain: ‘ONLINEBANK’
     Password:
          Checking connection ... connection successful
Do you confirm the Security Domain settings (y/n)? [n]: y
  1. When prompted, enter the password(s) for the security domain(s) and then enter y to confirm the settings.
    2. Note: If the password for one or more domains is incorrect, an error message is displayed.
    Copy
    Security Domain settings:
         Domain: ‘ONLINEBANK’
         Password:
              Checking connection ... connection successful
         Domain: ‘ENTERPRISE’
         Password:
              Checking connection ... connection failed
    Connection failed. Do you want to retry or exit (r/e)? [r]: r

    Enter r to retry, and then enter the correct password(s).

    If you enter e to exit, the migration operation is can celled.

Copy 
Please make sure the following listed key set is available.
 
Required keys to migrate domain ONLINEBANK:
         HID-IA-4T.AUDIT.1
         HID-IA-4T.DSIGN.1
         HID-IA-4T.CREDS.1
         HID-IA-4T.SYS.1
         HID-IA-4T.SESSION.1
 
Please confirm you really want to migrate the keys (y/n)? [n]: y
  1. Enter y to proceed.
Copy 
HSM Settings:
    Type (NCIPHER/NCIPHER_EMV/SAFENET)? []: NCIPHER
    Driver Home Directory [/opt/nfast]:
    Slot Number [0]:
    Operator PIN (or type enter if keys are module protected):
Please confirm you want to migrate to cryptographic slot 0 (y/n)? [n]: y
  1. Enter y to proceed.
Copy 
Migrating keys...
Keys have been migrated with success.

The script then re-encrypts and re-signs the data and updates the signatures of the database tables.

Migrate to a Different Slot of an External HSM

To change the HSM slot, you can specify the required slot in the cryptographic configuration. The key level index will be reset to 1 in the cryptographic configuration.

The script will get the targeted slot, check if the slot is PIN protected and, if so, prompt for the PIN, and then check the keys and migrate.

The following example illustrates how to migrate from slot 0 to slot 1 of an external HSM.

  1. Stop the ActivID AS services.
  2. As ftadmin, run the following command to migrate the cryptographic configuration.
Copy 
su ftadmin -c "<ACTIVID_HOME>/ActivID_AS/bin/migrationKeySetTool.sh -m"
 
Working in HSM mode.
 
Validate the specified domains:
--> Keys will be migrated for ONLINEBANK
 
You are about to migrate to a new key set.
This is a very sensitive operation and might take a long time.
The ActivlD applications will be unavailable during the entire process.
 
Important: All ActivlD AS services MUST be stopped.
In addition, as the entire database will be modified, make sure that you have created a backup.
Make sure that the new set of keys is available and accessible before you begin.
 
If an error occurs during the migration, please refer to the indicated log file.
If an error does occur, you might be required to restore the backup of the database to return to the functional configuration.
 
Do you really want to migrate the key set (y/n)? [n]: y 
  1. Enter y to proceed.
Copy 
Security Domain settings:
     Domain: ‘ONLINEBANK’
     Password:
          Checking connection ... connection successful
Do you confirm the Security Domain settings (y/n)? [n]: y
  1. When prompted, enter the password(s) for the security domain(s) and then enter y to confirm the settings.
    2. Note: If the password for one or more domains is incorrect, an error message is displayed.
    Copy
    Security Domain settings:
         Domain: ‘ONLINEBANK’
         Password:
              Checking connection ... connection successful
         Domain: ‘ENTERPRISE’
         Password:
              Checking connection ... connection failed
    Connection failed. Do you want to retry or exit (r/e)? [r]: r

    Enter r to retry, and then enter the correct password(s).

    If you enter e to exit, the migration operation is canceled.

Copy 
Please make sure the following listed key set is available.
 
Required keys to migrate domain ONLINEBANK:
         HID-IA-4T.AUDIT.1
         HID-IA-4T.DSIGN.1
         HID-IA-4T.CREDS.1
         HID-IA-4T.SYS.1
         HID-IA-4T.SESSION.1
 
Please confirm you really want to migrate the keys (y/n)? [n]: y
  1. Enter y to proceed.
Copy 
Please enter the cryptographic slot to use [0]: 1
Is the slot password protected (y/n)? [n]: y
Please enter the password for cryptographic slot 1:
Please confirm you want to migrate to cryptographic slot 1 (y/n)? [n]: y

  1. Enter y to proceed.

Copy 
Migrating keys...
Keys have been migrated with success.

The script then re-encrypts and re-signs the data and updates the signatures of the database tables.

See also:

Manage the Cryptography Keys