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.

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.

Supported algorithms for migration of CA and Certificates from KeySecure Classic to CipherTrust Manager:

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

1. In the Management Console, select the Security tab at the top of the page.

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

   {:.lightbox #NAE Server is configured to use LDAP user directory. Local users will not be recognized}

To View the LDAP Server Configuration

1. In the Management Console, select the Security tab at the top of the page.

2. 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 SSL Certificates

1. In the Management Console, select the Security tab at the top of the page.

2. In the left pane, under Device CAs & SSL Certificates, click SSL Certificates.

   

To View Local CAs

1. In the Management Console, select the Security tab at the top of the page.

2. In the left pane, under Device CAs & SSL Certificates, click Local CAs.

   

To View Known CAs

1. In the Management Console, select the Security tab at the top of the page.

2. In the left pane, under Device CAs & SSL Certificates, click Known CAs.

   The Known CAs screen shows (up to) 10 items per page by default.

   

To View ProtectDB Resources

1. In the Management Console, select the Security tab at the top of the page.

2. In the left pane, under ProtectDB Manager, click Databases.

   The Database Configuration screen shows existing database connections and database types.

   

   Note

   You can migrate both database connections and error replacement values.

To View the Objects to be Backed Up

1. In the Management Console, select the Security tab at the top of the page.

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

1. 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, local CAs, and Known CAs.

2. Select the Device tab at the top of the page.

3. In left pane, under Maintenance, navigate to Backup & Restore > Create Backup.

   Note

   This is the first of three Create Backup screens.

   

   Note

   For a successful migration, certificates along with their valid CAs must be part of the backup.

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

5. Select Continue. The second Create Backup screen is displayed.

   

   Note

   None of the Security items should be selected for migration.

6. Select Continue. The third Create Backup screen is displayed.

   

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

8. 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**.
   

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

10. 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:

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

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

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

   ksctl migrations status
   

   Response:

       {
         "id": "e7fe053f-2954-4a08-a5b4-4111d666f879",
         "overall_status": "Completed",
         "source": "KeySecure Classic",
         "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": "Completed",
           "num_processed": 0,
           "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": 0
         },
         "ldap_user_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "ldap_group_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "local_ca_status": {
           "status": "Completed",
           "num_processed": 1,
           "num_failed": 0,
           "num_ignored": 0
         },
         "certificate_status": {
           "status": "Completed",
           "num_processed": 1,
           "num_failed": 0,
           "num_ignored": 0
         },
         "external_ca_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pdb_connections_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 2
         },
         "pdb_err_rep_status": {
           "status": "Completed",
           "num_processed": 2,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pf_client_profile_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pf_shared_access_policy_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pf_file_server_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pf_local_rule_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pf_network_share_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pf_network_rule_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pf_rule_local_apg_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pf_cluster_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         },
         "pf_cluster_rule_status": {
           "status": "Completed",
           "num_processed": 0,
           "num_failed": 0,
           "num_ignored": 0
         }
       }
   

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

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

5. 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"
       }
   

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

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