Migrate KMIP Managed Objects from Data Security Manager

This document provides instructions to migrate KMIP managed objects from a Data Security Manager (DSM) to the CipherTrust Manager using the client utility.

Currently, the CipherTrust Manager supports migration of the following KMIP managed objects:
• Certificate
• Opaque Object
• Public Key
• Symmetric Key
• Private Key
• Secret Data

Currently, the CipherTrust Manager does not support migration of the following KMIP managed objects:
• Template
• SplitKey
• PGPKey

You can also migrate KMIP accessible agent keys and non-KMIP objects using the CipherTrust Manager CLI to restore a DSM backup file. We recommend restoring the backup to migrate these objects.

KMIP accessible agent keys are the only type of DSM object which can be migrated through both the client utility and ksctl. Both methods are idempotent, so migrating the same key object twice does not overwrite the key on CipherTrust Manager.

Prerequisites

• DSM version 6.4.3 or 6.4.4

• Ubuntu 18.04 LTS (Bionic Beaver) or RHEL 7.7 (Maipo)

• Client Utility (kmip-migration-utility-linux-amd64) and migration configuration file (migration.cfg) placed in the same folder on the Ubuntu/RHEL machine

• CipherTrust Manager 2.3.0 or higher

• The DSM appliance, CipherTrust Manager, and the KMIP migration utility – all must be connected to an active Internet connection, preferably on the same network

• Certificate and key file to connect to DSM KMIP port

• One DSM KMIP Agent License should be assigned to the migration utility on the DSM appliance

  If you do not have a DSM KMIP Agent license available internally, contact your Account team. They can provide you a temporary license.

Recommendations

This is a list of recommendations and precautionary measures for a successful migration:

• The DSM appliance, CipherTrust Manager, and the client migration utility must be on the same network for the best performance.

• Make sure that no key management operations are performed during the migration process.

• Create a backup of CipherTrust Manager and DSM server before initiating the migration process. If migration is not successful or there is any loss of data, then the user can restore the data using this backup.

• If DSM has an older version, then upgrade it to a supported version before proceeding with migration steps.

Understanding the Architectural Differences and Similarities

In DSM and CipherTrust Manager, domains are used for logically organizing and managing KMIP managed objects. Domains restrict the use of keys and security objects within the user and clients (for CipherTrust Manager) and hosts (for DSM) that belong to the domain.

During migration, the client utility transfers the KMIP managed objects within a domain from DSM to the specified domain in the CipherTrust Manager. The domain name can be specified in the configuration file.

Supported KMIP attributes in CipherTrust Manager

Supported attributes by CipherTrust Manager are set by the server as per KMIP specifications and stored in the object’s Meta. It also stores the attributes that are supported by DSM but not by CipherTrust Manager. For information on the above listed attributes, refer to the OASIS KMIP Documentation.

For Opaque Objects, the supported attributes are:
• ID
• Data Type
• Data Value
Other opaque object attributes are stored in the object’s meta.

The Structure type values of custom attributes are not supported.

High Level Migration Steps

Let's consider a scenario where a user wants to migrate objects from DSM to CipherTrust Manager. Let's assume that this user is in a domain and has a host. Now, perform the following steps:

1. Create a domain with the same name in the CipherTrust Manager to remove ambiguity

2. Create a User on the CipherTrust Manager with the name that you want to set as the owner of the object to be migrated

3. Grant permission to this User to perform the key management operations

4. Create a KMIP client using the DSM KMIP trusted CA and client certificate

5. Specify the required inputs in the migration configuration file (migration.cfg) and run the client migration utility (kmip-migration-utility-linux-amd64)

These are the high level steps that need to be performed to ensure an error free environment for a successful migration. These steps are explained in detail in the next section.

The client utility can migrate objects of only one DSM domain to the CipherTrust Manager. If it is required to migrate objects of multiple domains, the client utility needs to be configured and run individually for each domain.

Objects migrated from the DSM to CipherTrust Manager will have a prefix dsm- in their names on the CipherTrust Manager to identify them uniquely.

If no domain is specified in the configuration file during migration, the migration of the KMIP objects from DSM will be mapped to the root domain of the CipherTrust Manager.

Before Running the Client Migration Utility

1. Unzip the migration package at some location in Ubuntu/RHEL machine. The unzipped package contains the following files:

   • Read Me file (Readme.txt)

   • Client Utility (kmip-migration-utility-linux-amd64)

   • Sample Configuration File (sample.cfg)

   • Migration Configuration File (migration.cfg)

2. Preparing DSM:

   If you are not familiar with the DSM appliance, it is strongly advised to refer to the DSM User Manual for related information and instructions before performing these steps.

   a. Create a backup of DSM.

   b. Make sure that KMIP is configured and enabled for the host in that domain and DSM KMIP trusted CA is added.

   c. Open migration.cfg file and update:

   • KEYSOURCE_CERT_FILE (Specify path of the client certificate file to communicate with the DSM KMIP port)

   • KEYSOURCE_KEY_FILE (Specify path of the client key file to communicate with the DSM KMIP port)

3. Preparing CipherTrust Manager:

   If you are not familiar with CipherTrust Manager appliance, it is strongly advised to refer to its documentation for related information and instructions, before performing these steps. These steps can only be performed by a user with administrator privileges, and are explained in detail in next sections.

   a. Create a backup of the CipherTrust Manager.

   b. Create a domain corresponding to the DSM domain.

   c. Upload KMIP Trusted CA from DSM to CipherTrust Manager as an external CA. Now, add this uploaded CA in the trusted CA list of the respective KMIP interface.

   d. Create a User with the name that you want to set as the owner of the object to be migrated.

   e. Specify this User as Admin for the domain.

   f. Provide permission to this User to perform key management operations. You can do this by adding this User to the Key Admins and Key Users groups.

4. Prepare migration configuration file:

   Open the migration configuration (migration.cfg) file. You need to update the following fields:

   CipherTrust Manager Configuration

   Configuration Field	Description
   CM_IP	Specify the IP address of the CipherTrust Manager.
   CM_CONNECTION	Specify the name of the connection. Default value is Local.
   CM_DOMAIN	Specify the name of the domain.
   CM_KEY_OWNER_ID	Specify the owner of the keys to be migrated on the CipherTrust Manager. This user will be owner of the KMIP managed objects migrated from the DSM. It is a mandatory field. The CM_KEY_OWNER_ID can be specified in the local|<user-id> format.

   DSM Configuration

   Configuration Field	Description
   KEYSOURCE_NAME	Specify the name of the key source to be used as prefix. Default value is DSM.
   KEYSOURCE_IP	Specify the IP address of the DSM appliance.
   KEYSOURCE_KMIP_PORT	Specify the KMIP port for the DSM appliance.
   KEYSOURCE_BATCH_SIZE	Specify the batch size. Default value is 100. Note: Batch size is the number of items to be migrated in one iteration. This is useful in cases where network connection is slow or erratic. It is recommended to use a value equal to or less than 1000 in this field.
   KEYSOURCE_TOTAL_ITEMS	Specify the total number of items that you wish to migrate. Default value is 20000. Note: It is recommended to use a value equal to or less than 20000 in this field.
   KEYSOURCE_CERT_FILE	Specify path of the DSM client’s certificate file (.pem format).
   KEYSOURCE_KEY_FILE	Specify path of the DSM client’s key file (.key format).
   THREADS	CipherTrust Manager supports multithreading while migration of objects from DSM. Specify the number of threads you want to utilize depending on your hardware configuration and network latency. Recommended value for this variable is 5, but if there are frequent issues/errors related to the connectivity, then decrease its value.

Running the Client Migration Utility

Use one of the following commands to run the client migration utility:

If you want to migrate all types of managed objects, run:

./kmip-migration-utility-linux-amd64

If you want to migrate a specific type of managed object, run:

./kmip-migration-utility-linux-amd64 –-objects "<object name>"

Example: To migrate symmetric keys only

./kmip-migration-utility-linux-amd64 --objects "Symmetric Key"

If you want to migrate more than one type of managed objects, run:

./kmip-migration-utility-linux-amd64 –-objects "<Object-Name1>, <Object-Name2>"

Example: To migrate only public keys and certificates

./kmip-migration-utility-linux-amd64 --objects "Public Key,Certificate"

If you want to migrate multiple objects using their UUIDs, then create a file and mention the respective UUIDs in it, one entry per line. Use the following command:

./kmip-migration-utility-linux-amd64 –-filename <filename>

Example: To migrate KMIP managed objects whose UUIDs are mentioned in uuid_list.txt, run:

./kmip-migration-utility-linux-amd64 –-filename uuid_list.txt

The utility will prompt you for following inputs:

• CipherTrust Manager Username and Password.

Enter the login credentials of the user with administrator privileges.

• Permission to initiate the migration.
  Press Yes or Y to proceed.

It might take some time to migrate all the KMIP objects. You can view the migration logs to monitor the migration status. After successful migration, the client utility closes.

Migration logs can be viewed in the kmip-migration.log file.

After migration, the Fresh Attribute, Custom Attribute, Application Specific Information, and Digest Attribute get stored in the Key Meta.

After Running Client Migration Utility

Register the KMIP client on CipherTrust Manager using the DSM KMIP trusted CA uploaded on the CipherTrust Manager as an external CA. For details, refer to the 2nd step of KMIP Client Registration section.

Now, this CipherTrust Manager KMIP client can be used to perform the KMIP operations on the migrated objects.

Use the private key and certificate of the registered KMIP client to connect to the CipherTrust Manager’s KMIP port. This grants the user operational access to the migrated objects in the CipherTrust Manager.

If you want to migrate more domains, make corresponding changes in the migration configuration file and repeat the migration procedure.

Example Scenario

Let's assume a following scenario, where:

• Domain in DSM is D1

• DSM KMIP CA is DSM_CA

• Create a User U1 on the CipherTrust Manager that you want to set as the owner of the object to be migrated

• Create a domain D1 with the same name in the CipherTrust Manager for the simplicity

Now, update the migration configuration file (migration.cfg) to enable the DSM (set KEYSOURCE_NAME = DSM), client utility, and CipherTrust Manager to communicate with each other.

After everything is ready, run the migration utility (kmip-migration-utility-linux-amd64).

Once objects are migrated, register the KMIP client in the CipherTrust Manager to use these objects.

Let’s understand the above process through following steps:

Step 1: Create a user in the CipherTrust Manager

1. Log in to the CipherTrust Manager GUI as an administrator.

2. Navigate to the Access Management > Users. Click Create New User.

3. Specify Username, Email, Password, Password Match and click Create.

Step 2: Create a domain in the CipherTrust Manager with the same name

1. Navigate to Admin Settings > Domains. Click Add Domain.

2. Specify D1 in the name field.

3. Select Admins, Parent CA and click Save.

Step 4: Update migration configuration file and run the client utility

1. Update the required details in migration configuration (migration.cfg) file.

2. Open Terminal in Ubuntu/RHEL machine and run the client migration utility (kmip-migration-utility-linux-amd64).

Step 5: Register a KMIP Client in the CipherTrust Manager

After the migration is successful, you need to register the KMIP client in the CipherTrust Manager to perform the KMIP operations on the migrated objects.

1. Log in to the CipherTrust Manager GUI and switch to domain ‘D1’.

2. Create a KMIP Client Profile:

   a. Navigate to KMIP > Client Profile. Click Add Profile.

   b. Specify a Profile Name. In this example, let's proceed with P1 as the client profile name.

   c. Select CN as Username Location in the Certificate.

   d. Click Certificate Details and specify the D1||U1 in the Common Name field. Click Save.

   Here, the Common Name is specified in the format:
   <domain_name>|<connection_name>|<user_name>

   The <connection_name> is set to local in this case (therefore, it is not specified).

3. Create a Registration Token:

   a. Navigate to KMIP > Registration Token. Click New Registration Token.

   b. Specify a Name Prefix. Set values for Token Lifetime, Certificate Duration, and Client Capacity. Click Select CA.

   c. Select CA Type as External.

   d. Select DSM_CA from the External CA drop-down list. Click Select Profile.

   e. Select P1 as the client profile. Click Create Token.

   f. Copy the token. Click Done.

4. Add a Registered Client:

   a. Navigate to KMIP > Registered Clients. Click Add Client.

   b. Specify C1 as name of the KMIP Client.

   c. Paste the Registration Token. Click Save.

Limitations

• The client utility can migrate objects of only one DSM domain to the CipherTrust Manager at a time.

• LDAP users are not supported.

Troubleshooting Errors

This section includes the errors you may face while migrating from DSM to CipherTrust Manager. This is not an exhaustive list.

Configuration Related Errors

Migration Related Errors