Your suggested change has been received. Thank you.


Suggest A Change….


Getting Started

Migrate from Data Security Manager


Please Note:

Migrate from Data Security Manager

You can restore the following objects from a Data Security Manager (DSM) 6.4.x backup file using the CipherTrust Manager CLI tool ksctl:

The DSM Administration Guide version 6.4.9 describes creating and encrypting a backup file for CipherTrust Manager in Chapter 12 "Backing Up and Restoring".

Key Custom Attributes after Migration

When you migrate keys (symmetric, symmetric vault, asymmetric, asymmetric vault) from DSM to CipherTrust Manager, the name of the custom attributes of the DSM keys are changed and tagged as custom attributes under the "meta" section. The mapping of custom attribute names is as follows.

DSM Custom AttributesNAE Custom Attributes
Cryptographic Usage MaskCKA_VORM_CRYPTO_USAGE_MASK

In the above table, the DATE attribute contains only the date whereas, the _EL attribute is the epoch time.

Skipped Objects

Some objects present in the backup file are skipped during restore. The skipped objects include:

  • Most Key Management Interoperability Protocol (KMIP) keys, except for KMIP-accessible agent keys

  • Keys associated with CipherTrust Cloud Key Manager (CCKM), including Key Management as a Service (KMaaS) keys

  • DSM hostname and host configuration

Object Permissions After Migration

By default, the user who restores the backup file becomes the administrator of the newly created CipherTrust Manager domain(s), and has access to the restored keys within the domain(s). There is an additional option to create a key-sharing group with permissions for the restored keys in all domains. You can later add CipherTrust Manager users to this group to grant access to the keys.

In addition, the optional parameter auto-cte-groups in the ksctl migration command induces CipherTrust Manager to automatically detect CTE keys and grant permission to access these keys to members of the CTE Clients group on CipherTrust Manager.

After migration, the CipherTrust Manager domain administrator is able to delete migrated keys by default, even though DSM admins were not able to delete VAE keys. If you want to ensure that any migrated keys are not deletable, edit the key attributes to make the key undeletable.

Migrating KMIP Accessible Agent Keys

In DSM, KMIP accessible agent keys created on DSM have two copies. One copy is included in the DSM backup file, and can be restored on CipherTrust Manager with the ksctl CLI. The other copy is stored as a KMIP object, and displayed in Keys > KMIP objects on the DSM UI. CipherTrust Manager only retains one copy of the key after migration.

A separate client utility can migrate all objects displayed in Keys > KMIP Objects, including agent key copies. This utility connects directly to KMIP interfaces on both key managers instead of acting on the 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 processes are idempotent, so migrating the same key object twice does not overwrite the key on CipherTrust Manager.

We recommend migrating KMIP accessible agent keys through ksctl.

CipherTrust Manager Changes from Thales eSecurity DSM

  • No hypervisor limitation - so it can run on any cloud

  • Improved User Interface

  • Updated REST interface that offers both encryption and configuration in scope

  • Addition of a full-featured, remote CLI interface

  • Embedded CipherTrust Cloud Key Manager (removes the need for seperate MongoDB instance)

  • Unified Key Management with KMIP key material - integrates policy, logging and management - bringing simplified and richer capabilities to KMIP

  • Supports CipherTrust Transparent Encryption/CTE (renamed from VTE/Vormetric Transparent Encryption) from version 7.0

  • Supports CipherTrust Application Data Protection (CADP) as a replacement for Vormetric Application Encryption (VAE) and Vormetric Key Management (VKM)

  • All other connectors (Batch Data Transformation/BDT and Tokenization) are supported with latest versions

Exporting and Importing the Backup File

As part of exporting a backup file from a DSM, you create a wrapper key to encrypt the file. On the target CipherTrust Manager, you create a migration split key with the same values as the wrapper key. This migration split key is needed for CipherTrust Manager to decrypt the backup file to restore the DSM objects.

The wrapper key and migration split key divides a single key into multiple shares, with a minimum number of shares required to reassemble the key. This configuration, called M of N, provides more security as a different custodian holds and controls each share.

To migrate objects from DSM
  1. On your DSM appliance, create a wrapper key, and split it into key shares as described in the DSM Administration Guide version 6.4.9 Chapter 12 "Backing Up and Restoring".

    You need the following values to later create the corresponding migration split key and key shares on CipherTrust Manager:

    • The wrapper key identifier

    • The Minimum Custodians Needed to assemble the wrapper key

    • The key material from the wrapper key shares

  2. Create a backup file on the DSM, using the wrapper key to encrypt the backup file, as described in the DSM Administration Guide version 6.4.9 Chapter 12 "Backing Up and Restoring".

    There are two backup types available for migration to CipherTrust Manager:

    • Manual Backup and Restore. This is a complete system backup of all DSM objects. The backup file can include objects that are not yet supported for migration to CipherTrust Manager. CipherTrust Manager skips these unsupported items and does not restore them.

    • Selective Backup. This option allows you to select individual keys, hosts, or policies within a DSM domain to include in the backup file.

    In some cases, the download of the DSM migration data might fail.
    To work around this issue:
    1. Run the DSM CLI commands maintenance > repair purgepolicyhistory.
    2. Retry the backup download.

  3. Create a migration split key on a CipherTrust Manager to decrypt the backup file.

    You cannot directly import a DSM-created wrapper key into the CipherTrust Manager. You must re-create the wrapper key as a migration split key.

    1. Create the migration split key.

      $ ksctl migration-split-keys create --name <name> --threshold <threshold> --digest <digest>

      You must provide:

      • a name for the key.

      • threshold — a minimum number of keys needed to reconstruct the split key, based on Minimum Custodians Needed from the DSM wrapper key.

      • digest — the identifier from the original DSM wrapper key.

    2. Create shares for the split key. Create as many as shares as indicated in the threshold value for the migration split key.

      $ ksctl migration-split-keys shares create --name <name> --share-key <share-key>
      $ ksctl migration-split-keys shares create --name <name> --share-key <share-key>

      You must provide the name of the migration split key and the key material from the DSM wrapper key share.

  4. Upload the backup file into the CipherTrust Manager. Use the chunk-size option for larger backup files to upload the file in chunks and avoid a timeout. Take note of the ID returned in the response.

    $ ksctl migrations upload --file <filename> [--chunk-size <upload_chunk_size_in_bytes>]


    Upload of larger backup files can sometimes time out with the error context deadline exceeded (Client.Timeout exceeded while awaiting headers). If you encounter this, you can repeat the command, using the chunk-size option.

  5. Apply the backup file.

    $ ksctl migrations apply --id <id> [--user <user-name> --password <user-password>] [--domains <DSM-domains>] [--group-name <DSM group name>]  [--auto-cte-groups]

    You must provide the id for the backup file. This was indicated when you uploaded the backup, or you can view it with the ksctl migrations list command.

    The following parameters are optional:

    • user — The CipherTrust Manager user who will become the administrator of the created domain(s) and the owner of the migrated keys within the domain(s). If not specified, the user currently logged on to ksctl is granted this permission. The user should have the admin privileges to perform the migration. The admin privileges can be revoked after migration and the "key user" permission is granted.

    • password — Password of the above CipherTrust Manager user.

    • domains — Limits the DSM domains that are restored. The accepted format is a comma-separate list of domain names.

    • group-name — Creates a new group with this name in every domain that is migrated. Users belonging to this group can access all keys in the domain.


      We recommend the setting --group-name "CTE Clients" if the VTE/CTE keys have the DSM hostname as the key source, as was the case in older DSM versions.

      For example, you can run ksctl migrations apply --id <backup_upload_id> --group-name "CTE Clients".

      Apply this setting if you are unsure if such keys are present, but are comfortable with every key in the backup being accessible to CTE clients.

    • auto-cte-groups — When present, automatically detects CTE keys and grants permission to access these keys to members of the CTE Clients group on CipherTrust Manager.

      If you are migrating CTE clients from DSM to CipherTrust Manager, we generally recommend including this parameter to ensure continuity of CTE client access to keys. There are some cases, identified below, when auto-cte-groups is not recommended.


      • If you are migrating from VAE to CADP for C, the group-name and auto-cte-groups are not required.

      • We recommend the setting --group-name "CTE Clients" instead if the VTE/CTE keys have the DSM hostname as the key source, as was the case in older DSM versions. We also recommend this setting if you are unsure if such keys are present, but are comfortable with every key in the backup being accessible to CTE clients after migration.

    You can check the status of the migration with ksctl migrations status.

  6. List your keys to ensure that DSM keys were successfully migrated into the CipherTrust Manager domain.

    $ ksctl --domain <domain-name> keys list

If you are migrating CTE configuration from a DSM to the CipherTrust Manager, then after the DSM is migrated successfully, you need to perform additional steps for the CTE clients. Refer to Migrating CTE Configuration from Data Security Manager for details.