Upgrade Client

Tip

Luna Cloud HSM Services provisioned through the Thales Data Protection on Demand marketplace user interfaces refer to a service client. Luna Cloud HSM Services provisioned through external marketplaces user interfaces refer to a partition client. The documentation refers to these components as the client.

DPoD releases updates for the client frequently. Regularly updating the client provides you with access to the latest bug fixes, firmware updates, cryptographic utilities, enhanced performance, and improved service resilience.

We recommend that you upgrade your client regularly, following any version or patch release. Check the CHANGELOG and the Universal Client Supported Versions with Luna Cloud HSM frequently to stay up-to-date on version releases or patch updates.

Updating your client does not impact the Luna Cloud HSM Service itself or any cryptographic objects stored on the service. As a best practice, back up any existing clients before proceeding with the upgrade to preserve the client's configuration.

Note

Using 10.7.2 or higher, users are no longer required to run setenv to configure the client to connect to the Luna Cloud HSM Service. However, setenv may still be used to configure the client for hybrid use cases or integrations where setting the ChrystokiConfigurationPath is required.

When upgrading be aware of the following:

• Upgrading one client does not disrupt other clients' access to a Luna Cloud HSM Service. If the client you are upgrading is the only client connected to a Luna Cloud HSM Service, you will lose access to that service until the upgrade is complete. As only one Windows client can connect to a particular service, Windows deployments require planning for the access disruption.
• Any manual updates you have made to the Chrystoki.confor crystoki-template.ini configuration file will not be copied following the client upgrade process. After the upgrade, you will need to re-apply any customization to the configuration file.
• If you are using the SafeNet CSP or SafeNet KSP as part of your application integration you will need to re-register the SafeNet CSP or SafeNet KSP libraries and the HSM partition slot with the new version of the client. Additionally, you need to re-copy the SafeNetKSP.dll to the C:\Windows\System32\ folder.
• Following the upgrade any integrated applications may need to be restarted, reset or reconfigured to use the new version of the client before they can connect to the upgraded client.
• Re-initializing the Luna Cloud HSM Service will reset the Luna Cloud HSM Service and remove any cryptographic objects. Do NOT re-initialize the Luna Cloud HSM Service following the client upgrade. Log into LunaCM using the previously set passwords for the service.

If you would like to test the updated client before upgrading any production services, we recommend you sign up for a subscriber tenant account to gain access to the newest client for testing. Users can sign up for a subscriber tenant through the Public Marketplace. Refer to the client Troubleshooting material for detailed information about common issues users may encounter with the client.

To upgrade your client to the latest version

1. Back up your existing client as described in Backing up your Luna Cloud HSM Service.

2. Log in to your subscriber tenant as an application owner user.

3. Navigate to the My Services tab and click the service name that you would like to upgrade the client for.

4. In the Create Client wizard, enter a Service Name (Example: service_upgraded_client.zip) and click Create Client.

   A new client generates and is provided for downloading and installing on the client machine.

   The client is a zip file that contains system information needed to connect your client machine to an existing partition. See the section client Contents for client content details.

5. Transfer the client to your machine. You can use SCP, PSCP, WinSCP, FTPS or other secure transfer tool to transfer the client.

6. Unzip the client.

7. Decompress the cvclient-min.zip or the cvclient-min.tar for your operating system. Extract the cvclient-min.* within the service_upgraded_client folder. Do not extract to a new cvclient-min directory.

   Windows: Decompress the cvclient-min.zip using an extraction tool.

   Linux: tar xvf cvclient-min.tar

8. Copy any manual updates or customization from your old client Chrystoki.conf (Linux) or crystoki.ini (Windows) file to the new Chrystoki.conf or crystoki.conf file. Do not remove anything from the new files [REST] or XTC sections.

   

   Note

   * If the environment variable ChrystokiConfigurationPath is set, ensure it points to the location of the newly added client.

   * If the environment variable ChrystokiConfigurationPath is not set, do nothing and run the client for the client directory.

9. Start LunaCM. From the directory where you unzipped the cvclient-min.zip file execute lunacm. If the command executes with no errors, your connection is working correctly.

   

   Warning

   Do not re-initialize the Luna Cloud HSM Service when upgrading to the new client. Initializing the Luna Cloud HSM Service will reset the service and remove any cryptographic objects.