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

• Ubuntu or RHEL

• 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

  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:

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

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.

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:

   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.

   c. Open migration.cfg file and update the following files to communicate with the DSM KMIP port:

   • KEYSOURCE_CERT_FILE - Specify the path of the KMIP client’s certificate file in the .pem format.

   • KEYSOURCE_KEY_FILE - Specify the path of the KMIP client certificate Key File (generated when the KMIP client certificate was signed by the Trusted CA Authority in the .key format).

3. Preparing 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 corresponding to the DSM domain.

   Note

   Ensure that the CipherTrust Manager domain name must match the DSM domain name.

   c. Upload KMIP Trusted CA from DSM to CipherTrust Manager as an External CA. To do so, log on to DSM as a System Administrator. Navigate to System > KMIP Trusted CA Certificates. Select CA certificate and export Certificate, copy and paste it as an External CA on the CipherTrust Manager target Domain.

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

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 on the CipherTrust Manager

ksctl users create --name <user-name> --pword <password>

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

ksctl domains create --name <domain-name> --admins <domain-admins> --parent-ca-id <root-ca-id> --jsonfile <json-file>

Step 3: 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 4: Register a KMIP Client on 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 on to the CipherTrust Manager GUI and switch to domain ‘D1’.

2. Create a KMIP Client Profile:

   UI

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

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

   3. Select CN as Username Location in the Certificate.

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

   ksctl

   Use the below command to create a KMIP client profile:

   ksctl kmip createprofile --profilename <profile-name> --kmipprof <profile-config-json-file>
   

   In the above command,

   • profilename - name of the KMIP client profile.

   • kmipprof - JSON file that contains profile configuration details.

3. Create a Registration Token:

   UI

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

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

   3. Select CA Type as External.

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

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

   6. Copy the token. Click Done.

   ksctl

   Use the below command to create a registration token:

   If client registration is through local CA

   ksctl kmip createkmipregtoken --profilename <kmip-profile-name> --configfile <config-json-file>
   

   In the above command,

   • profilename - name of the KMIP client profile. The profilename is required and must be present in the system before creating a registration token.

   • configfile - JSON file that contains configuration details.

   If client registration is through external CA

   ksctl kmip createkmipregtoken –--profilename <kmip-profile-name> --configfile <config-json-file> --ca_id <CA-Id-of-the-external-CA>
   

   In the above command,

   • profilename - name of the KMIP client profile.

   • kmipprof - JSON file that contains profile configuration details.

   • ca_id - ID of the trusted Certificate Authority that will be used to sign client certificate during registration process. To register a client using external CA, make sure to upload the external CA to CipherTrust Manager, and the ca_id parameter must be set to the ID of the uploaded external CA.

4. Add a Registered Client:

   UI

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

   2. Specify C1 as name of the KMIP Client.

   3. Paste the Registration Token. Click Save.

   ksctl

   Use the below command to add a registered client:

   If client registration is through local CA

   ksctl kmip register --name <kmip-client-name> --regtoken <reregistration-token> --kmipCertOutFile <kmip-cert-out-file> --kmipKeyOutFile <kmip-key-out-file> --configfile <config-json-file>
   

   In the above command,

   • name - name of the KMIP client.

   • regtoken - registration token.

   • kmipCertOutFile - filename of the certificate to be written to in the "pem" format.

   • kmipKeyOutFile - Filename of the Private key to be written to in the "pem" format.

   • configfile - JSON file that contains configuration details.

   If client registration is through external CA

   ksctl kmip register --name <kmip-client-name> --regtoken <reregistration-token> --configfile <config-json-file> --cert <path-to-external-client-certificate>
   

   In the above command,

   • name - name of the KMIP client profile.

   • regtoken - JSON file that contains profile configuration.

   • configfile - JSON file that contains configuration details.

   • cert - KMIP client certificate file signed from an External CA.

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