Migrate from KeySecure Classic
If you have a legacy KeySecure k450 or k460 appliance, it may be running KeySecure Classic or NextGen KeySecure firmware.
To access latest CipherTrust Manager firmware if you are starting from a k450 or k460 appliance, you must migrate your data to a new CipherTrust Manager appliance.
Note
Upgrading KeySecure Classic k450 or k460 to use CipherTrust Manager firmware is not supported in CipherTrust Manager 2.8 or higher. Previous CipherTrust Manager versions 2.0-2.7 have such support.
Note
If your appliance is a k470 or k570 running NextGen KeySecure or CipherTrust Manager firmware, you can perform a standard upgrade to deploy the latest CipherTrust Manager firmware.
CipherTrust Managers Changes from SafeNet KeySecure Classic
No hypervisor limitation - so it can run on any cloud
Improved User Interface
Addition of a RESTful interface
Addition of a full-featured, remote CLI interface
Backward compatibility with the KeySecure Classic NAE-XML interface and the suite of existing connectors
Key policies (time of day and rate limits) are no longer supported.
RC4, 56-bit DES, 112-bit Triple DES, and 168-bit Triple DES in ECB mode (CBC mode is okay) are not supported.
FPE is only supported with 256-bit keys. 128 and 192 are not supported.
RSA Export formats supported are PKCS 1 and 8 only.
Data Migration Overview
Migration from SafeNet KeySecure Classic is performed by creating a backup file in KeySecure Classic and importing that file into the CipherTrust Manager. The destination CipherTrust Manager can be a k470 or k570 physical appliance, or a virtual CipherTrust Manager instance.
The suggested version of KeySecure Classic version to migrate to CipherTrust Manager is 8.12. The minimum version is 8.4.3.
You must first decide what data on KeySecure Classic you wish to migrate. You then create queries to export only the data you wish to migrate. If desired, you can also backup and migrate all data.
After all data has been selected for migration, use KeySecure Classic's backup process to create data sets, which are typically downloaded to the user’s computer. Once the backup file has been downloaded it serves as input to the migration operations available using CLI tool ksctl, where it is first uploaded and then processed. After the data has been processed it can be queried using ksctl to verify that all data was correctly migrated.
Supported Migration Data
Supported migration data includes:
Keys
Local Users and Groups
LDAP Server Users and Groups
Managed Objects Certificates
Local CAs
Known CAs
SSL/TLS Certificates
ProtectDB Resources
Supported algorithms for migration of CA and Certificates from KeySecure Classic to CipherTrust Manager:
Note
RSA-768
, RSA-1024
, RSA-2048
, RSA-3072
, RSA-4096
, EC-secp224r1-224
, EC-secp384r1-384
, EC-secp521r1-521
, and EC-prime256v1-256
Unsupported Migration Data
Not all data on KeySecure Classic can be migrated to CipherTrust Manager.
We do not currently support migration of the following data:
Administration settings
High Security settings
IP Authentication
Key Server settings
FIPS status server
Log Signing Certificates
Logging related configuration
Network settings
Network Time Protocol (NTP) setting
Services
SSL/TLS settings
Syslog settings
Key Templates
Note
We plan to support migration of Key Templates in a future release.
Trusted CA Lists
User and Group Migration
When migrating a KeySecure Classic backup that has an LDAP configuration, only the LDAP configuration is migrated while all local users and groups are ignored.
There is no complete storage of LDAP users and groups on a KeySecure Classic system. Because of this, LDAP users and groups are created in the CipherTrust Manager system as the keys are parsed from the backup file. This prevents issues with orphan keys – keys that cannot be accessed because there is no user. The CipherTrust Manager system maintains a mapping between groups stored in the keys and local groups created in the CipherTrust Manager system. For further details on LDAP Group Mapping, go to LDAP Group Mapping.
Note
You can migrate selective users and groups from KeySecure classic 8.12.5 (and higher) to CipherTrust Manager 2.8 (and higher).
Note
The UI login is prevented for the local and LDAP users after migration to the CipherTrust Manager. For more details, refer to Preventing Users from UI Login.
Identifying Objects to be Backed Up
We begin by identifying the menu objects we intend to backup in KeySecure Classic .
To View Users and Groups
In the Management Console, select the Security tab at the top of the page.
In the left pane, under Users & Groups, navigate to Local Authentication > Local Users and Groups.
The Users and Groups screen shows (up to) 10 local users and (up to) 10 local groups.
The following message may also appear on the screen if LDAP is being used. This will not have an effect on backing up your data.
Note
{:.lightbox #NAE Server is configured to use LDAP user directory. Local users will not be recognized}
To View the LDAP Server Configuration
In the Management Console, select the Security tab at the top of the page.
In left pane, under Users and Groups, navigate to LDAP > LDAP Server.
The LDAP Server Configuration screen is displayed showing the LDAP configuration on this machine
Note
Since this KeySecure Classic system is configured to use LDAP, only LDAP users will be migrated.
To View SSL Certificates
In the Management Console, select the Security tab at the top of the page.
In the left pane, under Device CAs & SSL Certificates, click SSL Certificates.
Note
Certificates only with valid local CAs will be migrated. Self-signed and imported certificates will not be migrated.
Certificate revocation details will be migrated with "certificateHold" as the revocation reason.
Note
If an externally imported CA and its certificates are used in the NAE/KMIP interface of KeySecure Classic, the CA will be migrated as an External CA, but the certificates will not be migrated to the CipherTrust Manager.
Therefore, to use the same certificate for the NAE/KMIP interface in the CipherTrust Manager, select the migrated external CA and upload its certificate manually by editing the NAE interface on the CipherTrust Manager.
Similarly, if a local CA and its certificates are used in the NAE/KMIP interface of KeySecure Classic, use auto-generation or issue a new certificate and upload the certificate to the interface.
To View Local CAs
In the Management Console, select the Security tab at the top of the page.
In the left pane, under Device CAs & SSL Certificates, click Local CAs.
Note
In case of incomplete local CA chain, all the child resources (certificates and CAs) will not be migrated.
The CipherTrust Manager does not support local CA revocation. Therefore, the details of local CA revocations will not be migrated. Only the revocation details of certificates signed by the local CA will be migrated.
To View Known CAs
In the Management Console, select the Security tab at the top of the page.
In the left pane, under Device CAs & SSL Certificates, click Known CAs.
The Known CAs screen shows (up to) 10 items per page by default.
To View ProtectDB Resources
In the Management Console, select the Security tab at the top of the page.
In the left pane, under ProtectDB Manager, click Databases.
The Database Configuration screen shows existing database connections and database types.
Note
You can migrate both database connections and error replacement values.
To View the Objects to be Backed Up
In the Management Console, select the Security tab at the top of the page.
In left pane under Managed Objects, navigate to Keys > Key List.
The Key List screen is displayed showing (up to) 10 keys that are stored in the platform, with a default Query of [All].
A new query can be created to select a subset of the keys in the platform. This is initiated by selecting Create Query at the bottom of this screen.
If a subset is selected, make sure that all keys to be migrated are included in one of the queries.
Note
If multiple queries are defined, be sure that no keys match multiple queries. The migration will reject any key that is duplicated. This will not fail the migration but it will create error messages that must be investigated.
For more information about the creation and use of key queries, refer to the KeySecure Classic Help documentation, Administration Guide > Key Management > Creating a Key Query.
Creating a Backup File
All backup operations are done within KeySecure Classic. Familiarity with its user interface is assumed.
For more information about Creating a Backup, refer the KeySecure Classic Help documentation, Administration Guide > Backup and Restore > Creating a Backup.
To Create a Backup on KeySecure Classic
Log in to the Management Console as an administrator with the appropriate backup access control. There are specific access controls for backing up configuration, keys & certificates, local CAs, and Known CAs.
Select the Device tab at the top of the page.
In left pane, under Maintenance, navigate to Backup & Restore > Create Backup.
Note
This is the first of three Create Backup screens.
Note
To migrate selective users and groups, provide comma-separated values as demonstrated in the above image.
Note
For a successful migration, certificates along with their valid CAs must be part of the backup.
Select the configuration items to include in the backup file. Use the Select All button to select all items on the page.
When selecting Managed Objects, you have the option of selecting all keys, no keys, specific keys, or backing up the results of a query. You can view query results using the Show Results button. When selecting Certificates and Local Certificate Authorities, you can select all, none, or select items from a list. The All keys and All certificates options are dynamic. This means if you select these options, schedule an automated backup and subsequently create new keys and certificates. The new keys and certificates will be included in the next scheduled backup.
Select Continue. The second Create Backup screen is displayed.
Note
None of the Security items should be selected for migration.
Select Continue. The third Create Backup screen is displayed.
Enter backup file information: name, description, and password:
Backup Name - Enter a name for the backup. Use only letters and numbers. Special characters and white space are not allowed in backup names. For backups stored externally, the backup filename is created by appending
_0_bkp
to this name. For large backups, the zero is incremented by 1 for each additional file. For example, backup foo could consist of two files:foo_0_bkp
andfoo_1_bkp
.Backup Description - Enter a short description for the backup.
Backup Password - Enter a password for your backup file. Remember, this file contains very valuable information and will likely have a long life span. Use an appropriately complex password. The password can have a maximum of 30 characters.
Warning
The backup file cannot be restored without this password.
Enter the Destination of the file.
The backup configuration can be downloaded to a browser or copied to another machine via FTP or SCP. To use SCP with a new host, first add the destination host to the Known Hosts list, as described in the KeySecure Classic Help documentation Administration Guide > Known Hosts.
Warning
Do not store the backup configuration locally on the KeySecure Classic. Backup files stored on the KeySecure Classic are not available to migrate to a CipherTrust Manager.
If you download the backup configuration to a browser, the backup configuration is encrypted and downloaded to your local machine. You must specify a name for the file; however, it is not necessary to specify an extension for the file.
If you select FTP or SCP to copy the backup configuration to another machine, you must provide the following:
the destination host.
the name of the directory on the destination host. (You must have write permission for this directory.)
the username of the account on the destination host.
(FTP) the password for the user account on the destination host.
(SCP only) The authentication method, Key or Password. To use Key authentication with a new remote host, first add the SafeNet KeySecure's SSH Key to the destination host, as described in the KeySecure Classic Help documentation Administration Guide > SSH Public Key.
Before proceeding, review the Backup Summary listing at the bottom of the third Create Backup screen. If you need to make changes, use the Back button to return to appropriate screen and make the necessary edits. After making changes, you may have to re-enter data in the third Create Backup screen.
If you need to complete a one-time backup immediately, select Backup Now to create and store the backup file, then click Save. Confirm your save when requested to do so.
Note
The backup you have defined is started immediately when you click Backup Now. The detailed settings used by Backup Now processing are not preserved, so you may wish to keep a record of these settings yourself.
It is possible to create multiple backups and migrate each of them separately. The only issue is that duplicate data (keys, users, configuration) will display error messages to that effect. If you run the same file multiple times without changes on the CipherTrust Manager system, duplicate data error messages will also occur. There is no harm in doing so. If changes are made to the CipherTrust Manager system between migration attempts (for example, deleting records that were migrated) then those 'duplicate data' errors will not occur.
Migrating the Backup File
The CLI tool, ksctl is used to perform migrations.
To get help with ksctl migration commands, type the following:
ksctl migrations --help
The following ksctl commands are used for migration:
upload Upload a 'KeySecure Classic' backup file.
apply Migrate the specified 'KeySecure Classic' backup file to a KeySecure.
list List available 'KeySecure Classic' backup files.
get Get information about a specific 'KeySecure Classic' backup file.
status Get the status of the ongoing (or last) migration.
delete Delete a 'KeySecure Classic' backup file.
log Get the migration log of the ongoing or last migration of this backup.
To migrate your backup file to the CipherTrust Manager system
Note
If your CipherTrust Manager is part of a cluster, you only need to migrate the backup file to one node. The data replicates to all the other members of the cluster.
UPLOAD: The first step in a migration will be to upload a KeySecure Classic backup file. This process is done with the ksctl upload command:
ksctl migrations upload --file <ks-classic-backup-file>
The following flags can be set for convenience:
--desc <backup description>
A description of the backup can be stored.
--checksum <sha256-sum>
If the user computes a checksum of the backup, enter that value here. The checksum of the file will be returned when the file upload is complete, these numbers must match for the upload to be successful.
--chunk-size 10000000
To expedite uploads, this will set the chunksize used for data transfers from the client to the host.
--upload-id <upload-id>
Used when resuming chunked uploads. May be specified when starting a chunked upload.
When the upload is complete a response is received:
{ "id": "36828f00-fad8-4dc2-9854-44ed1dfdfb2b", "file_size": 55751, "created_at": "2018-09-19T21:24:20.196984173Z", "checksum_sha256": "69fdf386bacb9ab322db15acdc25cd4ab2b68c2c1a13b128d2225589db208638" }
Note
The value of the id field is used in many of the following steps.
APPLY: After the file has been uploaded, the user must start the migration process, since it does not start automatically. To start the process use the apply command:
ksctl migrations apply --id <id> --migpassword <password used in backup> -e <user type>
If LDAP configuration information is included in the backup, then this information should be indicated on the command line using the
-e
and-n
flags. The-e
(user type) is a mandatory parameter and its value can beldap
orlocal
, depending on whether the users in the backup are local or ldap users.ksctl migrations apply –i <id> -p <backup password> -e ldap –n <ldap conn>
Note
Either local or LDAP users can be migrated in a single apply command. Also, as detailed earlier, local users are invisible on a system configured for LDAP usage.
STATUS: The status of the last migration can be queried with the status command:
ksctl migrations status
Response:
{ "id": "e7fe053f-2954-4a08-a5b4-4111d666f879", "overall_status": "Completed", "source": "KeySecure Classic", "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": 0, "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": 0 }, "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 }, "local_ca_status": { "status": "Completed", "num_processed": 1, "num_failed": 0, "num_ignored": 0 }, "certificate_status": { "status": "Completed", "num_processed": 1, "num_failed": 0, "num_ignored": 0 }, "external_ca_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 }, "pdb_connections_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 2 }, "pdb_err_rep_status": { "status": "Completed", "num_processed": 2, "num_failed": 0, "num_ignored": 0 }, "pf_client_profile_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 }, "pf_shared_access_policy_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 }, "pf_file_server_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 }, "pf_local_rule_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 }, "pf_network_share_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 }, "pf_network_rule_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 }, "pf_rule_local_apg_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 }, "pf_cluster_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 }, "pf_cluster_rule_status": { "status": "Completed", "num_processed": 0, "num_failed": 0, "num_ignored": 0 } }
If errors are indicated in the status above, then the
ksctl migrations log
command should be run (see below).LIST: To get list of migration files loaded on the platform, use the list command:
ksctl migrations list
This will return information about all of the migrations that are stored on the platform as follows:
{ "skip": 0, "limit": 10, "total": 2, "resources": [ { "id": "36828f00-fad8-4dc2-9854-44ed1dfdfb2b", "file_size": 55751, "created_at": "2018-09-19T21:24:20.196984173Z", "checksum_sha256": "69fdf386bacb9ab322db15acdc25cd4ab2b68c2c1a13b128d2225589db208638" }, { "id": "878a711e-1dcb-41f6-8cb1-fa0cd2105070", "file_size": 55751, "created_at": "2018-09-12T19:24:43.237843362Z", "checksum_sha256": "c7dcf3229e3b28edd3fa763b07b756009face6277cee7d80fe4cbad891f72f2f" } ] }
There are two command line options that can be useful if a large number of migrations are stored on the platform, those options are
--limit
and--skip
.The purpose of
--limit
is to let ksctl know how many records (maximum) should be retrieved and displayed in the response. The purpose of--skip
is to let ksctl know how many records to ignore in the platform before returning responses. For example, if there are 100 migrations stored and you wish to only retrieve information about records 20-50, type the following command:ksctl migrations list --limit 30 --skip 20
GET: To retrieve information about a single migration, use the
get
command:ksctl migrations get --id
where
is the migration ID returned in the upload of the backup. When this command is run, the response is: { "id": "36828f00-fad8-4dc2-9854-44ed1dfdfb2b", "file_size": 55751, "created_at": "2018-09-19T21:24:20.196984173Z", "checksum_sha256": "69fdf386bacb9ab322db15acdc25cd4ab2b68c2c1a13b128d2225589db208638" }
LOG: If the user wishes to retrieve the log created by the CipherTrust Manager system, use the
log
command:ksctl migrations log --id <id>
This will return a log listing each user or key for which there was an attempt at migration. The success or failure of that attempt will be detailed. This is the command to run where there are errors reported in the
status
command above. The error messages should be explanatory in regards to the problem with the migration. If a resolution cannot be determined, contact Customer Support for the CipherTrust Manager system. For contact information, refer to Support Contacts.Example log file messages:
2018-09-21 15:15:40 | migration start | success | 878a711e-1dcb-41f6-8cb1-fa0cd2105070 2018-09-12 19:30:17 | migrate key | success | 'beta3-2327-aes256', version 0 2018-09-12 19:30:17 | migrate key | ignore | 'beta3-2327-des', version 0 - unsupported key size 64 for TDES; 2018-09-12 19:30:17 | migrate key | fail | 'beta3-2327-desede', version 0 - The default IV size must be 16 2018-09-12 19:30:17 | migrate key | success | 'beta3-2327-hmacsha1', version 0 2018-09-12 19:30:17 | migrate key | ignore | 'beta3-2327-rc4', version 0 - unsupported algorithm 'RC4'; 2018-09-12 19:30:17 | migrate key | success | 'beta3-2327-rsa', version 0 2018-09-12 19:30:17 | migrate key | ignore | 'beta3-2327-seed', version 0 - unsupported algorithm 'SEED-CBC'; 2018-09-12 19:30:17 | migration finished | success |
Warning
This file will get extremely long for large migrations.
DELETE: Finally, to remove a migration file from the CipherTrust Manager system, use the
delete
command:ksctl migrations delete --id
If the
value exists in the CipherTrust Manager system, there is no visible response. If there are errors, ksctl will report them.