Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo
back

ProtectFile Administration

Migration from KeySecure Classic to CipherTrust Manager

search

Please Note:

Migration from KeySecure Classic to CipherTrust Manager

This document provides instructions to migrate encrypted ProtectFile clients from KeySecure Classic to CipherTrust Manager (formerly known as Next Generation KeySecure).

Supported Entities

Migration of the following entities is supported:

  • ProtectFile client profiles, network profiles

  • File servers, network shares, Windows clusters

  • Shared access policies, local encryption policies, and network encryption policies

Prerequisites

The following table lists minimum compatible versions of CipherTrust Manager, KeySecure Classic, and ProtectFile for migration.

KeySecure ClassicCipherTrust ManagerProtectFile
8.12.x2.xProtectFile Windows 8.12.3
8.12.x2.xProtectFile Linux 8.12.4p02

Important Notes

Read and understand the following information before proceeding with migration. This will help you plan an efficient migration.

  • Local access policies used with encryption policies will be converted to "Shared Access Policies" referred to as "Access Policy Groups" on CipherTrust Manager.

  • The "Network Share Profile" entities will not be visible on CipherTrust Manager. However, client-share associations will be created using these network profiles.

  • The "Fingerprint Check", the primary "KeySecure IP or Hostname", and the "Optional Failover IP or Hostname" fields from client profiles will not be migrated.

  • The "Allow Offline Storage" and "Offline Mode Timeout" fields related the offline mode will be migrated to CipherTrust Manager. However, the ProtectFile 8.12.x clients do not support the offline mode.

Encryption States Mapping

It is recommended that no rules are in transition states such as migration/key rotation/unencryption "in progress". The following table shows the mapping of encryption rules between the KeySecure Classic UI and CipherTrust Manager:

KeySecure Classic UICipherTrust Manager
Merge PendingThis state is dropped during migration
Preparing MergeThis state is dropped during migration
Merge in ProgressThis state is dropped during migration
Merge Completed with ErrorsThis state is dropped during migration
Merge CompleteThis state is dropped during migration
Migration PendingCreated
Preparing MigrationThis state is dropped during migration
Migration in ProgressThis state is dropped during migration
Migration Completed with ErrorsFailed
EncryptedEncrypted
Key Rotation PendingEncrypted (key changes reverted)
Key Rotation in ProgressThis state is dropped during migration
Unencryption PendingEncrypted (with current key)
Unencryption in ProgressThis state is dropped during migration

Migration Steps

High level activities involved in migrating clients configured with KeySecure Classic to CipherTrust Manager are:

  1. Backing up ProtectFile Manager on KeySecure Classic

  2. Applying the Backup to CipherTrust Manager

  3. Updating ProtectFile Client Profiles

  4. Upgrading ProtectFile Clients

  5. Migrating ProtectFile Clients to CipherTrust Manager

These steps are described below.

Backing up ProtectFile Manager on KeySecure Classic

Use the Create Backup wizard to back up the ProtectFile Manager configuration and ProtectFile keys on KeySecure Classic.

Migration of ProtectFile clients requires a backup of ProtectFile Manager and ProtectFile keys.

To back up ProtectFile Manager and ProtectFile keys:

  1. Log on to KeySecure Classic as an administrator with ProtectFile Manager access control.

  2. Navigate to the Create Backup screen of the Backup & Restore page (Device > Backup & Restore > Create Backup). The Security Items screen of the Create Backup wizard is displayed.

  3. Select Security Items:

    a. Select the ProtectFile Manager check box.

    b. Select All keys as Managed Objects.

    To back up specific keys, use a key query to specify the keys (select Choose from query and select the saved query). Refer to "Creating a Key Query" in the KeySecure Classic documentation for details on creating key queries.

    c. Click Continue.

    The Device Items screen of the Create Backup wizard is displayed. Selections on this screen do not have any impact on migration of ProtectFile clients.

  4. Click Continue. The Backup Settings screen of the Create Backup wizard is displayed.

  5. Specify Backup Settings.

    a. Specify the Backup Name. Use only letters and numbers. Special characters and whitespace are not allowed in backup names. For example, PFMBackup is the backup name in this document.

    b. Specify the Backup Description.

    c. Enter Backup Password and Confirm Backup Password. The password can have a maximum of 256 characters. For example, backuppass is the backup password name in this document.

    Remember the backup password. This password will be needed when applying the backup to CipherTrust Manager. The backup cannot be applied without this password.

    d. Select a destination for the backup file. Refer to "Creating a Backup" in the KeySecure Classic documentation for details.

    e. Review the Backup Summary.

  6. Click Backup Now. This backup may take as long as several minutes. Wait for the backup to complete.

Save the backup file at a secure location. This file will be needed when applying the ProtectFile Manager backup to CipherTrust Manager.

Applying the Backup to CipherTrust Manager

The backup file can be applied to CipherTrust Manager by using the ksctl migrations commands. Refer to "Migrating from KeySecure Classic > Migrating the Backup File" in CipherTrust Manager documentation for details on the ksctl migrations commands.

To apply the ProtectFile Manager backup to CipherTrust Manager:

  1. Upload the backup file to CipherTrust Manager. Run the ksctl migrations upload command. For example:

    
ksctl migrations upload --url <ks_url> --user <ks_user> --password <ks_user_password> --nosslverify -f

    For example, on Windows, run:

    
ksctl-win-amd64.exe --url https://10.164.12.210 --user admin --password adminpass --nosslverify migrations upload -f C:\Users\Admin\Downloads\PFMBackup
{
        "id": "69f541b2-d9db-43c9-a7da-bc2a4251b1c2",
        "file_size": 208286,
        "created_at": "2019-01-11T05:43:18.963991502Z",
        "checksum_sha256": "240ccfab5dd3b21759ec6aa7f5f96acdf2cbc7d04f150338bde2475674b7001d"
}

    The generated "id", for example, "69f541b2-d9db-43c9-a7da-bc2a4251b1c2" in the output above, will be needed when applying the backup.

  2. Apply the backup. Run the ksctl migrations apply command. For example:

    
ksctl migrations apply --url <ks_url> --user <ks_user> --password <ks_user_password> --nosslverify -i <id_gen_during_upload> -p <backup_password> -e local

    For example, on Windows, run:

    
ksctl-win-amd64.exe migrations apply --url https://10.164.12.210 --user admin --password adminpass --nosslverify -i 69f541b2-d9db-43c9-a7da-ba4251b1c2 -p backuppass -e local
{
        "id": "69f541b2-d9db-43c9-a7da-bc2a4251b1c2",
        "file_size": 208286,
        "created_at": "2019-01-11T05:43:18.963991502Z",
        "status": "In progress",
        "checksum_sha256": "240ccfab5dd3b21759ec6aa7f5f96acdf2cbc7d04f150338bde2475674b7001d"
}

  3. Verify the migration status. Run the ksctl migrations status command.

    
ksctl --url <ks_url> --user <ks_user> --password <ks_user_password> --nosslverify migrations status

    For example, on Windows, run:

    
ksctl-win-amd64.exe --url https://10.164.12.210 --user admin --password adminpass --nosslverify migrations status
{
        "id": "69f541b2-d9db-43c9-a7da-bc2a4251b1c2",
        "overall_status": "Completed",
        "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": 1,
                "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": 1
        },
        "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
        },
        "pf_client_profile_status": {
                "status": "Completed",
                "num_processed": 3,
                "num_failed": 0,
                "num_ignored": 0
        },
        "pf_shared_access_policy_status": {
                "status": "Completed",
                "num_processed": 9,
                "num_failed": 0,
                "num_ignored": 0
        },
        "pf_file_server_status": {
                "status": "Completed",
                "num_processed": 1,
                "num_failed": 0,
                "num_ignored": 0
        },
        "pf_local_rule_status": {
                "status": "Completed",
                "num_processed": 3,
                "num_failed": 0,
                "num_ignored": 0
        },
        "pf_network_share_status": {
                "status": "Completed",
                "num_processed": 5,
                "num_failed": 0,
                "num_ignored": 0
        },
        "pf_network_rule_status": {
                "status": "Not started",
                "num_processed": 0,
                "num_failed": 0,
                "num_ignored": 0
        },
        "pf_local_rule_apg_status": {
                "status": "Completed",
                "num_processed": 1,
                "num_failed": 0,
                "num_ignored": 0
        }
}

The status Completed confirms successful migration of all entities.

Applying the backup maps the configurations such as details about clients, client profiles, and access policies to appropriate entities on CipherTrust Manager. Refer to Supported Entities for details.

Updating ProtectFile Client Profiles

After the backup is applied to CipherTrust Manager, change or modify the client profiles according to your setup requirements.

Upgrading ProtectFile Clients

Upgrade ProtectFile versions running on encrypted clients to a ProtectFile version compatible with CipherTrust Manager; for example, 8.12.x or higher. It is recommended to upgrade to the latest available compatible version.

Upgrade all the existing ProtectFile clients to be migrated. Perform the steps listed in this section on all ProtectFile clients.

Upgrading Windows Clients

ProtectFile driver binaries are signed by secured SHA-256. Before upgrading ProtectFile on 64-bit Windows Server 2008 R2 SP1, ensure that the Security Update (KB3033929) for Windows 64-bit is installed. After installing the update, the system must be restarted. Refer to the Microsoft Knowledge Base article (KB3033929) for details.

If the update is not installed, ProtectFile upgrade aborts with the warning message, Microsoft Windows update, KB3033929, is needed. Install the update before proceeding. Aborting installation!

ProtectFile can be upgraded to the latest version either manually (by walking through the installation wizard) or silently (from the command line).

Manual Upgrade

To upgrade ProtectFile Windows:

  1. Stop all operations on protected paths.

  2. Download the compatible ProtectFile installer from the Technical Support Customer Portal.

  3. Log on to the client as a user with administrator rights.

  4. Launch the InstallShield Wizard. A message appears stating that ProtectFile will be upgraded.

  5. Click Yes to continue. The Resuming the InstallShield Wizard for ProtectFile screen appears.

  6. Click Next. The Files in Use screen appears.

  7. Select ProtectFile Service.

  8. Select Automatically close and attempt to restart applications. The installer will close the opened applications.

    If Do not close applications. (A reboot will be required) is selected, applications remain opened, but a reboot is required after installation.

  9. Click OK. The Installing ProtectFile screen appears. The installer shuts down the opened applications. Depending on the number of opened applications, this step might take significant amount time to complete.

  10. Click Finish on the InstallShield Wizard Complete screen. A message appears prompting to restart the client for the upgrade to be effective.

  11. Restart the server now. The upgrade will be effective after reboot.

ProtectFile is now upgraded.

Silent Upgrade

Alternatively, ProtectFile can be upgraded from the command line. This is called silent upgrade.

Silent ProtectFile upgrade would cause the client to restart.

To perform silent ProtectFile upgrade:

  1. Stop all operations on protected paths.

  2. Download the compatible ProtectFile installer from the Technical Support Customer Portal.

  3. Log on to the client as a user with administrator rights.

  4. Open the command prompt.

  5. Navigate to the folder where the ProtectFile installer (ProtectFile-x.-x64.exe) is stored.

  6. Run "ProtectFile-<version number>.x-x64.exe" /s /v/qn. For example:

    
C:\Users\Administrator\Downloads>"ProtectFile-8.12.x.x-x64.exe" /s /v/qn

    Restart the server now. The upgrade will be effective after reboot. Successful upgrade can be confirmed under Control Panel > All Control Panel Items > Programs and Features.

Upgrading Linux Clients

ProtectFile can be upgraded using standard packages or interactively using the interactive installer. If ProtectFile is installed using standard packages, it can be upgraded using standard packages only. Similarly, if it is installed interactively, it can be upgraded using interactively installer only. Before upgrading ProtectFile, ensure that:

  • CipherTrust Manager is running a compatible version.

  • No protected paths are in use.

Upgrading ProtectFile Using Standard Packages

ProtectFile installed using standard packages can be upgraded using standard packages only.

Upgrade on Ubuntu Platforms

To upgrade ProtectFile on Ubuntu, run:


sudo dpkg -i safenet-pf-8.12.x.xxx-xxx_amd64.deb
Upgrade on Linux Platforms

To upgrade ProtectFile to 8.12.x, run the following command:


rpm -Uvh safenet_pf-8.12.x.xxx-xxx.x86_64.rpm

After upgrading ProtectFile by using the rpm -Uvh command, either restart the client or reload the safenetfs kernel module. All existing encryption policies remain as earlier.

NOTES:

While upgrading ProtectFile, the following errors might occur:

  • FATAL: Module safenet_crypt_<soft|aesni> is in use.

  • FATAL: Module safenetfs is in use.

If the above errors occur, do either of the following:

  • Reload kernel modules manually. To do so:

    a. Unmount the safenetfs mounts.

    b. Unload the existing kernel modules by running:

    
rmmod safenet_crypt_<soft|aesni> safenetfs

    c. Restart the ProtectFile service.

  • Reboot the client.

Upgrading ProtectFile Interactively

The ProtectFile interactive installer works with platforms and kernels supported by ProtectFile 8.12.x. Refer to ProtectFile Clients 8.12.x Customer Release Notes for the complete list of supported kernels.

ProtectFile installed interactively can be upgraded using the interactive installer only. While upgrading, the installer prompts for location of the init.conf file. This file is available where ProtectFile binaries and libraries are installed.

To upgrade ProtectFile interactively:

  1. Log on to the client as root. The installer script must be run as root.

  2. Navigate to the extracted safenet_pf-8.12.x.xxx-xxx directory. This is the directory where the interactive installer scripts were extracted during installation.

  3. Run the installer script in the upgrade mode, install_pf.sh -u.

    The install_pf.sh script must be run from the directory where it is extracted.

  4. Run: ./install_pf.sh –u

    For example:

    
[root@localhost safenet_pf-8.12.x.xxx-xxx]# ./install_pf.sh -u
Upgrading SafeNet ProtectFile Linux 8.12.x.xxx-xxx on kernel version 3.10.0-
327.18.2.el7.x86_64.
Continue[yes/no]:

  5. Enter yes to continue. yes is case-sensitive. Entering anything else (for example, no or Yes will close the installer script.

    For example: Continue [yes/no]: yes

  6. Specify location of the init.conf file. Refer to Installing ProtectFile Interactively for file location. The default location is /usr/lib/safenet/PF/bin.

    If binaries and libraries are installed at default location, /usr/lib/safenet/PF/bin, press Enter to continue. If they are installed at a different location, specify the location and press Enter. This document assumes that the init.conf file is available at default location.

    For example:

    
* Location of init.conf [/usr/lib/safenet/PF/bin]:
ProtectFile upgraded successfully!

The output shows that ProtectFile is upgraded successfully.

Migrating ProtectFile Clients to CipherTrust Manager

Migrate the upgraded ProtectFile clients to communicate with CipherTrust Manager. Run the Registration Utility (clientreg) with the --migrate (or -m) flag to migrate the clients. The utility requires a client registration token and the SHA256 or SHA512 fingerprint of the server certificate for migration.

Migrating ProtectFile Clients to CipherTrust Manager involves:

  1. Creating a Registration Token

  2. Getting the Fingerprint of the Server Certificate

  3. Running the Registration Utility in Migration Mode

These steps are described below.

Creating a Registration Token

A client registration token can be created on CipherTrust Manager. A CipherTrust Manager Administrator can create registration tokens.

To create a registration token, refer to Creating a Registration Token.

Getting the Fingerprint of the Server Certificate

The fingerprint of the server’s web interface certificate can be viewed on the GUI or the API playground. This fingerprint will be used when migrating clients.

To get the fingerprint of the server certificate, refer to Getting the Fingerprint of the Server Certificate.

Running the Registration Utility in Migration Mode

Run the Registration Utility with the --migrate (or -m) flag to migrate the clients.

Perform this step on all the upgraded ProtectFile clients.

Run the following command on the migrated client:

Linux Clients


clientreg --client-name <client_name> --ksip <keysecure_ip> [--port <keysecure_port>] --migrate --product-name ProtectFile --reg-token <registration_token> --server-cert-fp <fingerprint_of_server_certificate>

Windows Clients


clientreg.exe --client-name <client_name> --ksip <keysecure_ip> [--port <keysecure_port>] --migrate --product-name ProtectFile --reg-token <registration_token> --server-cert-fp <fingerprint_of_server_certificate>

Here,

  • --client-name (-n): Friendly unique name for the client on the CipherTrust Manager console. This parameter can be ignored during migration.

  • --ksip (-i): IP address or hostname of CipherTrust Manager to register clients.

  • --migrate (-m): Flag to specify a migration operation. This is mandatory for migrating clients from KeySecure Classic to CipherTrust Manager.

  • --port (-o): Port of the CipherTrust Manager to register clients. Use this option if the CipherTrust Manager is configured on a custom port (other than the default 443). If not specified, the default port is used.

  • --product-name (-p): (Optional) Product is ProtectFile when migrating a ProtectFile client. The default product is ProtectFile.

  • --reg-token (-t): Registration token generated on CipherTrust Manager. Refer to Creating a Registration Token for details.

  • --server-cert-fp (-f): Fingerprint of the server’s "web" interface certificate. Only SHA256 and SHA512 fingerprints are supported. Refer to Getting the Fingerprint of the Server Certificate for details.

    -n, -i, -p, -o, -t, -f, and -m represent the short forms of the Registration Utility flags. These short forms can also be used instead of full flag names. For example, use -m instead of --migrate to migrate a ProtectFile client from KeySecure Classic to CipherTrust Manager.

For example, on Linux run:


clientreg --client-name MigLinClient1 --ksip 10.164.12.120 --migrate --product-name ProtectFile --reg-token f0OqnH2MA1mo6o2MqZx6eFJ23cK27AAcYKx3SMh8JKcaYGy6ypVOfKaaDoMuCinx --server-cert-fp D4011E2469D09DDCF8D09EB2552B549D3E8FA24AFC7C7DE2B6020DF58D5D06DB

For example, on Windows run:


clientreg.exe --client-name MigWinClient1 --ksip 10.164.12.120 --migrate --product-name ProtectFile --reg-token f0OqnH2MA1mo6o2MqZx6eFJ23cK27AAcYKx3SMh8JKcaYGy6ypVOfKaaDoMuCinx --server-cert-fp D4011E2469D09DDCF8D09EB2552B549D3E8FA24AFC7C7DE2B6020DF58D5D06DB

Migration registers the upgraded ProtectFile clients with CipherTrust Manager.