Upgrading from KeySecure Classic Firmware

If your SafeNet KeySecure k450 or k460 appliance is still running Keysecure Classic firmware, you must perform the tasks below to deploy the CipherTrust Manager firmware.

You require physical access to your appliance in your data center.

Tasks for Deploying CipherTrust Manager Firmware

1. Backup your existing keys, local, users, and groups.

2. Install the CipherTrust Manager firmware as an upgrade.

3. Establish a connection and change default passwords.

4. k460 only: Initialize and configure the SafeNet Luna PCIe HSM Card within the appliance, allowing the HSM card to act as the root of trust.

5. Import your backup file to recover your previous data.

Backup Keys

Back up keys, local users and groups, and LDAP server users and groups. Save the backup configuration outside the appliance. See Creating a Backup File for detailed description of these tasks.

Firmware Installation

After taking a backup of the k450 or k460 appliance, install the CipherTrust Manager firmware on the appliance:

1. Create a DVD from the ISO provided by Gemalto.

2. Boot the system from the DVD.

   The installation proceeds automatically.

Establish a Connection and Change Default Passwords

After you have installed the CipherTrust Manager firmware, you must log in to the console to create a secure password for the ksadmin user, and then log in to the GUI to change the default SSH key and admin user password. Changing these defaults ensures the security of CipherTrust Manager and is required before beginning to create keys or engage in any other cryptographic usecases.

Connecting the Appliance to a Console Device

From the console you log in a the System Administrator ('ksadmin' user), create a secure password, start-up the system and access the IP address of the Graphical User Interface (GUI). You can connect a computer directly to the console port of the CipherTrust Manager Appliance using a serial connection.

Direct administration connection to the console via serial terminal is required for these reasons:

• During initial configuration, you do not yet know the IP address dynamically allocated by your DHCP server.

• After deployment, if you re-configure network settings (change the IP address) via SSH, you will lose the old IP address connection.

To open a serial connection:

1. Open a connection between the serial port on the appliance's rear panel to a terminal server, dumb terminal, PC, or laptop.

2. When the connection is made, IP address information appears together with the appliance log in prompt: keysecure login:

   Note

   You may need to press ENTER several times to initiate the session.

   Note

   Windows 10 occasionally crashes when trying to detect a serial port. This is a known issue with the Windows 10 PL2303 drivers. If you experience trouble opening a serial connection using Windows 10, use another supported operating system.

3. As the System Administrator, enter "ksadmin" to log in and follow the prompts to create a secure password.

   Caution

   Be sure to retain this password - it will be required to access the system in case of network connectivity problems.

   The system starts up, which can take several minutes.

Connecting to the GUI for the First Time

1. After the system starts up, in the Console Window, choose the KeySecure IP address for your network. Use this address to browse to the CipherTrust Manager GUI.

   Note

   The initial IP address is set via DHCP, which is displayed in the Console Window. If you need to set a static IP address, you can set it from the console using the nmcli tool after initializing the appliance. For details, refer to the Network Interface Configuration.

   The initial CipherTrust Manager GUI screen is displayed:

   

   The error displayed is normal and simply requires the default SSH Public Key to be replaced.

2. As the System Administrator (ksadmin), paste in your SSH Public Key in the box provided and then select Add.

   Note

   The SSH Public Key must be a 'PEM-formatted RSA key'. You can generate this key using 'PuTTYgen' or similar utility. Save this SSH Public Key at a safe location. You will need this key for future SSH access.

   After replacing the default SSH Public Key, the Log In screen appears. For more options to replace the default SSH Public Key, see Starting Services After Deployment

   Warning

   Be sure to store and securely protect the associated private SSH key, as this key will be required to SSH to the appliance from this point on.

   The initial Application Administrator can now log in.

3. Log in using the initial default credentials: Username = admin, Password = admin

   The following notice is displayed:

   

   Note

   If the default credentials do not work, you may need to retrieve an autogenerated password, as described in Changing the Initial Password.

4. Enter a new password using this default Password Policy:

   Min length: 8
   Max length: 30
   Min number of upper cases: 1
   Min number of lower cases: 1
   Min number of digits: 1
   Min number of other characters: 1
   

   A new Login screen appears.

5. Using your new password, log in again. The CipherTrust Manager Web Page appears.

   

HSM Configuration for k460

HSM configuration must be performed for k460 devices before beginning to create keys or engage in any other cryptographic usecases.

1. As the System Administrator (ksadmin) SSH in to the appliance (or connect via serial port using your password) and execute "/usr/safenet/lunaclient/bin/lunacm" utility.

   The utility displays information on the detected HSM card and allows you to execute various HSM management commands.

   Refer to the Luna PCIe HSM 6.x documentation for more details on these HSM commands.

2. Re-initialize the HSM.

   lunacm:> hsm factoryReset
   lunacm:> hsm init -label <hsmLabel>
   

   At this point, you are prompted to imprint or provide a blue HSM Security Officer (SO) PED key and a red Cloning Domain PED key on the PED. Follow PED prompts to either create new PED keys with new authentication, or to re-use existing PED keys to imprint their authentication on to the HSM.

3. Login as the HSM SO. You are prompted for the blue PED key.

   lunacm:> hsm login
   

4. Create the partition to hold the CipherTrust Manager root of trust keys.

   lunacm:> partition create
   

   At this point, you are prompted to imprint or provide a black Partition Crypto Officer(CO) PED key on the PED. Follow PED prompts to create a new black PED key with new authentication, or to re-use an existing black PED key to imprint its authentication on to the new partition.

5. If you have created a new black PED key, you need to create a challenge password so that you can authenticate to the partition without access to the PED.

   1. Login as the HSM SO. Present the blue PED key as prompted.

      hsm login
      

   2. Create the challenge secret text string.

      lunacm:> partition createChallenge
      

      The PED screen displays a generated string of characters that you must record accurately and promptly.

   3. Record the text string. We recommend recording in a text editor to avoid future problems with reading handwriting.

6. Login to the partition with the black PED key, and activate the partition.

   Note

   This instructs the HSM to cache PED credentials and allows the k460 appliance to authenticate to the HSM using only the challenge secret (password) without requiring the black PED key to always be connected to the HSM. However, in the event of a power outage of more than 2 hours, the HSM cached PED credentials will expire and the k460 appliance will fail to run its services. In this case, instruct the k460 appliance to re-authenticate with the HSM using the black PED key.

   lunacm:> partition login lunacm:> partition changepolicy -policy 22 -value 1 lunacm:> partition changepolicy -policy 23 -value 1 lunacm:> partition activate

7. Log out and login again to cache the Crypto Officer credentials.

   lunacm:> partition logout
   lunacm:> partition login
   

8. Exit the lunacm utility.

HSM Root of Trust Configuration

Configure the k460 appliance to use the Luna PCIe HSM card using these steps:

1. Access the 'partition-label' and the 'partition challenge' created during the HSM initialization procedure. These are needed to use the CipherTrust Manager HSM API or CLI hsm setup command.

2. You are now ready to configure the HSM as Root of Trust. Refer to CipherTrust Manager HSM Setup API or the CLI hsm setup command to configure the appliance to use your newly initialized Luna PCIe HSM. Root of Trust Configuration provides more details.

Migrating the Backup File

The CLI toolksctl 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:

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

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

   If LDAP configuration information is included in the backup, then this should be indicated on the command line with the –-e and –-n flags.

   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.

3. STATUS: The status of the last migration can be queried with the status command:

   ksctl migrations status
   

   Response:

       {
         "id": "878a711e-1dcb-41f6-8cb1-fa0cd2105070",
         "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": "Failed",
           "num_processed": 16,
           "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
         }
       }
   

   If errors are indicated in the status above, then the ksctl migrations log command should be run (see below).

4. 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 list -–limit 30 –-skip 20
   

5. 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"
       }
   

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

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