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.

You can also migrate KMIP accessible agent keys using the CipherTrust Manager ksctl to restore a DSM backup file.

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 higher

• CipherTrust Manager 2.3.0 or higher

• Ubuntu or RHEL to run the migration utility

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

• Certificate and key file required to connect migration utility with DSM KMIP port. Refer to DSM Configuration.

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

  Note

  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:

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

• Ensure no operations are being performed on DSM during the migration process to avoid any conflict.

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

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 are stored in the object’s metadata as per KMIP specifications on CipherTrust Manager. It also stores the attributes that are exclusively supported by DSM only. For more information on the above listed attributes, refer to the OASIS KMIP Documentation.

Migration Steps

Pre-Migration

Perform the following pre-migration configuration:

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

   Note

   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.

   Note

   The same set of certificate and key will be used in KMIP migration utility. You can set these in the migration.cfg by providing the path where your certificate and key exsists.

   • KEYSOURCE_CERT_FILE=/home/cert.pem

   • KEYSOURCE_KEY_FILE=/home/key.pem

3. Configuring CipherTrust Manager

   Note

   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 on CM where the object will be migrated. In case no domain is created, the object will be will be migrated to root domain.

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

   e. 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_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.
   KEYSOURCE_CERT_FILE	Specify path of the DSM client’s certificate file (.pem format). If you do not have an existing certificate, you can create a new certificate and use the same on DSM to connect to the KMIP utilty. Refer to Generating the Certificates.
   KEYSOURCE_KEY_FILE	Specify path of the DSM client’s key file (.key format). If you do not have an existing key, you can create a new key while creating the certificate and use the same on DSM to connect to the KMIP utilty. Refer to Generating the Certificates.
   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.

Post-Migration

After successful migration, the client can perform all the KMIP operations on the migrated objects. For additional steps required for the KMIP client to communicate with the CipherTrust Manager, refer to the Integration Guide for the respective client, available on Thalesdocs.

Limitations

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

• LDAP users are not supported.

Appendix

Generating the Certificates

This section provides information to generate the Client Certificate, Key, and CA (Optional).

Sample Command:

openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 365 -key ca.key -out ca.crt
openssl genrsa -out user.key 2048
openssl req -new -key user.key -out user.csr
openssl x509 -req -days 365 -in user.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out user.crt

Creating KMIP client on DSM

1. Create a user with all privileges.

   Note

   If you already have a DSM KMIP Agent license available, skip Step 2 or contact your Account team. They can provide you a temporary license.

2. Upload KMIP license. Navigate to System > License > Upload KMIP license.

3. Create Domain, enable KMIP, and assign created user.

4. Logout and login again with the User created above. Navigate to System > Upload KMIP trusted CA. Upload the root CA from which client certificate and private key is created.

5. Switch domain. Navigate to Hosts > Add hosts. Ensure Host name to be equal to value of CN in client certificate. Select the KMIP check box. Select the Communication enabled check box. Click Import KMIP Certificate to upload the client certificate.

6. Use the above created KMIP client to communicate to the KMIP utility through 5696 KMIP port.

Troubleshooting

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