Please Note:

You are not viewing the most recent version of this page. 2.19 is the latest version available.

Migrating KeySecure Classic Data to a CipherTrust Manager Appliance

This chapter describes how to migrate objects from a SafeNet KeySecure Classic system to the CipherTrust Manager system.

Overview

Migration from SafeNet KeySecure Classic is performed by creating a backup file in KeySecure Classic and importing that file into the CipherTrust Manager. The destination CipherTrust Manager can be a k470 or k570 appliance, or it can be a k450 or k460 upgraded to CipherTrust Manager Firmware.

You must first decide what data on KeySecure Classic you wish to migrate. You then create queries to export only the data you wish to migrate. If desired, you can also backup and migrate all data.

Note

Supported migration data include keys, local users and groups, as well as LDAP server users and groups.

After all data has been selected for migration, use KeySecure Classic's backup process to create data sets, which are typically downloaded to the user’s computer. Once the backup file has been downloaded it serves as input to the migration operations available using CLI tool ksctl, where it is first uploaded and then processed. After the data has been processed it can be queried using ksctl to verify that all data was correctly migrated.

User and Group Migration

When migrating a KeySecure Classic backup that has an LDAP configuration, only the LDAP configuration is migrated while all local users and groups are ignored.

There is no complete storage of LDAP users and groups on a KeySecure Classic system. Because of this, LDAP users and groups are created in the CipherTrust Manager system as the keys are parsed from the backup file. This prevents issues with orphan keys – keys that cannot be accessed because there is no user. The CipherTrust Manager system maintains a mapping between groups stored in the keys and local groups created in the CipherTrust Manager system. For further details on LDAP Group Mapping, go to LDAP Group Mapping.

Identifying objects to be Backed-up

We begin by identifying the menu objects we intend to backup in KeySecure Classic .

To view Users and Groups

In the Management Console, select the Security tab at the top of the page.
In the left pane, under Users & Groups, navigate to Local Authentication > Local Users and Groups.
The Users and Groups screen shows (up to) 10 local users and (up to) 10 local groups.
The following message may also appear on the screen if LDAP is being used. This will not have an effect on backing up your data.
Note

To view the LDAP Server Configuration

In the Management Console, select the Security tab at the top of the page.
In left pane, under Users and Groups, navigate to LDAP > LDAP Server.
The LDAP Server Configuration screen is displayed showing the LDAP configuration on this machine
Note
Since this KeySecure Classic system is configured to use LDAP, only LDAP users will be migrated.

To view the objects to be backed up.

In the Management Console, select the Security tab at the top of the page.
In left pane under Managed Objects, navigate to Keys > Key List.
The Key List screen is displayed showing (up to) 10 keys that are stored in the platform, with a default Query of [All].
A new query can be created to select a subset of the keys in the platform. This is initiated by selecting Create Query at the bottom of this screen.
If a subset is selected, make sure that all keys to be migrated are included in one of the queries.
Note
If multiple queries are defined, be sure that no keys match multiple queries. The migration will reject any key that is duplicated. This will not fail the migration but it will create error messages that must be investigated.
For more information about the creation and use of key queries, refer to the KeySecure Classic Help documentation, Administration Guide > Key Management > Creating a Key Query.

Creating a Backup File

All backup operations are done within KeySecure Classic. Familiarity with its user interface is assumed.

For more information about Creating a Backup, refer the KeySecure Classic Help documentation, Administration Guide > Backup and Restore > Creating a Backup.

To create a backup on KeySecure Classic:

Log in to the Management Console as an administrator with the appropriate backup access control. There are specific access controls for backing up configuration, keys & certificates, and local CAs.
Select the Device tab at the top of the page.
In left pane, under Maintenance, navigate to Backup & Restore > Create Backup.
Note
This is the first of three Create Backup screens.
Note
For the purposes of migration, the only items of interest in release 1.5 of CipherTrust Manager system are Keys, Local Users & Groups as well as LDAP Server Users & Groups.
Select the configuration items to include in the backup file. Use the Select All button to select all items on the page.
When selecting Managed Objects, you have the option of selecting all keys, no keys, specific keys, or backing up the results of a query. You can view query results using the Show Results button. When selecting Certificates and Local Certificate Authorities, you can select all, none, or select items from a list. The All keys and All certificates options are dynamic. This means if you select these options, schedule an automated backup and subsequently create new keys and certificates. The new keys and certificates will be included in the next scheduled backup.
Note
The Log Signing Certificate is not included with the other certificates on the device. To backup the Log Signing Certificate, you must specifically select it on the next screen by selecting Continue.
Select Continue. The second Create Backup screen is displayed.
Note
None of the Security items should be selected for migration.
Select Continue. The third Create Backup screen is displayed.
Enter backup file information: name, description, and password:
1. Backup Name - Enter a name for the backup. Use only letters and numbers. Special characters and white space are not allowed in backup names. For backups stored externally, the backup filename is created by appending _0_bkp to this name. For large backups, the zero is incremented by 1 for each additional file. For example, backup foo could consist of two files: foo_0_bkp and foo_1_bkp.
2. Backup Description - Enter a short description for the backup.
3. Backup Password - Enter a password for your backup file. Remember, this file contains very valuable information and will likely have a long life span. Use an appropriately complex password. The password can have a maximum of 30 characters.
  Warning
  The backup file cannot be restored without this password.
Enter the Destination of the file.
The backup configuration can be downloaded to a browser or copied to another machine via FTP or SCP. To use SCP with a new host, first add the destination host to the Known Hosts list, as described in the KeySecure Classic Help documentation Administration Guide > Known Hosts.
Warning
Do not store the backup configuration locally on the KeySecure Classic. Backup files stored on the KeySecure Classic are not available to migrate to a CipherTrust Manager.
If you download the backup configuration to a browser, the backup configuration is encrypted and downloaded to your local machine. You must specify a name for the file; however, it is not necessary to specify an extension for the file.
If you select FTP or SCP to copy the backup configuration to another machine, you must provide the following:
```
* the destination host.

* the name of the directory on the destination host. (You must have write permission for this directory.)

* the username of the account on the destination host.

* (FTP) the password for the user account on the destination host.

* (SCP only) The authentication method, Key or Password. To use Key authentication with a new remote host, first add the SafeNet KeySecure's SSH Key to the destination host, as described in the KeySecure Classic **Help** documentation **Administration Guide > SSH Public Key**.
```
Before proceeding, review the Backup Summary listing at the bottom of the third Create Backup screen. If you need to make changes, use the Back button to return to appropriate screen and make the necessary edits. After making changes, you may have to re-enter data in the third Create Backup screen.
If you need to complete a one-time backup immediately, select Backup Now to create and store the backup file, then click Save. Confirm your save when requested to do so.
Note
The backup you have defined is started immediately when you click Backup Now. The detailed settings used by Backup Now processing are not preserved, so you may wish to keep a record of these settings yourself.
It is possible to create multiple backups and migrate each of them separately. The only issue is that duplicate data (keys, users, configuration) will display error messages to that effect. If you run the same file multiple times without changes on the CipherTrust Manager system, duplicate data error messages will also occur. There is no harm in doing so. If changes are made to the CipherTrust Manager system between migration attempts (for example, deleting records that were migrated) then those 'duplicate data' errors will not occur.

Migrating the Backup File

The CLI toolksctl is used to perform migrations.

To get help with ksctl migration commands, type the following:

ksctl migrations -–help

The following ksctl commands are used for migration:

upload      Upload a 'KeySecure Classic' backup file.
apply       Migrate the specified 'KeySecure Classic' backup file to a KeySecure.
list        List available 'KeySecure Classic' backup files.
get         Get information about a specific 'KeySecure Classic' backup file.
status      Get the status of the ongoing (or last) migration.
delete      Delete a 'KeySecure Classic' backup file.
log         Get the migration log of the ongoing or last migration of this backup.

To migrate your backup file to the CipherTrust Manager system:

Note

If your CipherTrust Manager is part of a cluster, you only need to migrate the backup file to one node. The data replicates to all the other members of the cluster.

UPLOAD: The first step in a migration will be to upload a KeySecure Classic backup file. This process is done with the ksctl upload command:
```
ksctl migrations upload –-file <ks-classic-backup-file>
```
The following flags can be set for convenience:
```
--desc <backup description>
```
A description of the backup can be stored.
```
--checksum <sha256-sum>
```
If the user computes a checksum of the backup, enter that value here. The checksum of the file will be returned when the file upload is complete, these numbers must match for the upload to be successful.
```
--chunk-size 10000000
```
To expedite uploads, this will set the chunksize used for data transfers from the client to the host.
```
--upload-id <upload-id>
```
Used when resuming chunked uploads. May be specified when starting a chunked upload.
When the upload is complete a response is received:
```
{
  "id": "36828f00-fad8-4dc2-9854-44ed1dfdfb2b",
  "file_size": 55751,
  "created_at": "2018-09-19T21:24:20.196984173Z",
  "checksum_sha256": "69fdf386bacb9ab322db15acdc25cd4ab2b68c2c1a13b128d2225589db208638"
}
```
Note
The value of the id field is used in many of the following steps.
APPLY: After the file has been uploaded, the user must start the migration process, since it does not start automatically. To start the process use the apply command:
```
ksctl migrations apply –-id <id> --migpassword <password used in backup>
```
If LDAP configuration information is included in the backup, then this should be indicated on the command line with the –-e and –-n flags.
```
ksctl migrations apply –i <id> -p <backup password> -e ldap –n <ldap conn>
```
Note
Either local or LDAP users can be migrated in a single apply command. Also, as detailed earlier, local users are invisible on a system configured for LDAP usage.

STATUS: The status of the last migration can be queried with the status command:

ksctl migrations status

Response:

{
  "id": "878a711e-1dcb-41f6-8cb1-fa0cd2105070",
  "overall_status": "Completed",
  "users_status": {
    "status": "Completed",
    "num_processed": 0,
    "num_failed": 0,
    "num_ignored": 0
  },
  "groups_status": {
    "status": "Completed",
    "num_processed": 0,
    "num_failed": 0,
    "num_ignored": 0
  },
  "groups_members_status": {
    "status": "Completed",
    "num_processed": 0,
    "num_failed": 0,
    "num_ignored": 0
  },
  "keys_status": {
    "status": "Failed",
    "num_processed": 16,
    "num_failed": 0,
    "num_ignored": 0
  },
  "keys_links_status": {
    "status": "Completed",
    "num_processed": 0,
    "num_failed": 0,
    "num_ignored": 0
  },
  "ldap_server_status": {
    "status": "Completed",
    "num_processed": 0,
    "num_failed": 0,
    "num_ignored": 1
  }
}

If errors are indicated in the status above, then the ksctl migrations log command should be run (see below).

LIST: To get list of migration files loaded on the platform, use the list command:

ksctl migrations list

This will return information about all of the migrations that are stored on the platform as follows:

{
  "skip": 0,
  "limit": 10,
  "total": 2,
  "resources": [
      {
          "id": "36828f00-fad8-4dc2-9854-44ed1dfdfb2b",
          "file_size": 55751,
          "created_at": "2018-09-19T21:24:20.196984173Z",
          "checksum_sha256": "69fdf386bacb9ab322db15acdc25cd4ab2b68c2c1a13b128d2225589db208638"
        },
      {
          "id": "878a711e-1dcb-41f6-8cb1-fa0cd2105070",
          "file_size": 55751,
          "created_at": "2018-09-12T19:24:43.237843362Z",
          "checksum_sha256": "c7dcf3229e3b28edd3fa763b07b756009face6277cee7d80fe4cbad891f72f2f"
      }
    ]
  }

There are two command line options that can be useful if a large number of migrations are stored on the platform, those options are --limit and --skip.

The purpose of --limit is to let ksctl know how many records (maximum) should be retrieved and displayed in the response. The purpose of --skip is to let ksctl know how many records to ignore in the platform before returning responses. For example, if there are 100 migrations stored and you wish to only retrieve information about records 20-50, type the following command:

ksctl list -–limit 30 –-skip 20

GET: To retrieve information about a single migration, use the get command:

ksctl migrations get –-id

where is the migration ID returned in the upload of the backup. When this command is run, the response is:

{
  "id": "36828f00-fad8-4dc2-9854-44ed1dfdfb2b",
  "file_size": 55751,
  "created_at": "2018-09-19T21:24:20.196984173Z",
  "checksum_sha256": "69fdf386bacb9ab322db15acdc25cd4ab2b68c2c1a13b128d2225589db208638"
}

LOG: If the user wishes to retrieve the log created by the CipherTrust Manager system, use the log command:

ksctl migrations log –-id <id>

This will return a log listing each user or key for which there was an attempt at migration. The success or failure of that attempt will be detailed. This is the command to run where there are errors reported in the status command above. The error messages should be explanatory in regards to the problem with the migration. If a resolution cannot be determined, contact Customer Support for the CipherTrust Manager system. For contact information, refer to Support Contacts.

Example log file messages:

2018-09-21 15:15:40 | migration start | success | 878a711e-1dcb-41f6-8cb1-fa0cd2105070
2018-09-12 19:30:17 | migrate key | success | 'beta3-2327-aes256', version 0
2018-09-12 19:30:17 | migrate key | ignore | 'beta3-2327-des', version 0 - unsupported key size 64 for TDES;
2018-09-12 19:30:17 | migrate key | fail | 'beta3-2327-desede', version 0 - The default IV size must be 16
2018-09-12 19:30:17 | migrate key | success | 'beta3-2327-hmacsha1', version 0
2018-09-12 19:30:17 | migrate key | ignore | 'beta3-2327-rc4', version 0 - unsupported algorithm 'RC4';
2018-09-12 19:30:17 | migrate key | success | 'beta3-2327-rsa', version 0
2018-09-12 19:30:17 | migrate key | ignore | 'beta3-2327-seed', version 0 - unsupported algorithm 'SEED-CBC';
2018-09-12 19:30:17 | migration finished | success |

Warning

This file will get extremely long for large migrations.

DELETE: Finally, to remove a migration file from the CipherTrust Manager system, use the delete command:
```
ksctl migrations delete –-id
```
If the value exists in the CipherTrust Manager system, there is no visible response.
If there are errors, ksctl will report them.

Migrating KeySecure Classic Data to a CipherTrust Manager Appliance

Overview

User and Group Migration

Identifying objects to be Backed-up

To view Users and Groups

To view the LDAP Server Configuration

To view the objects to be backed up.

Creating a Backup File

To create a backup on KeySecure Classic:

Migrating the Backup File

To migrate your backup file to the CipherTrust Manager system:

On this page

Suggest A Change