Your suggested change has been received. Thank you.

close

Suggest A Change

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

back

Luna Cloud HSM Clients

Troubleshoot Client

search

Troubleshoot Client

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

This page provides troubleshooting details for common minor errors and solutions that you may encounter with your Luna Cloud HSM Service.

Client Connectivity Support Tool

The client connectivity support tool is an executable utility which validates the client connection to the Luna Cloud HSM Service. The lch-support-linux-64bit (Linux) and lch-support-win-64bit (Windows) is included in the client package downloaded from the Luna Cloud HSM Service.

The client connectivity support tool incrementally validates the client connection to the Luna Cloud HSM Service. If a validation step fails the check is marked as FAIL and any subsequent connectivity checks are marked as SKIP. To return more detailed errors run the tool with --verbose.

For more information about the client connection to the Luna Cloud HSM Service see Client Network Connectivity and Service Client Communication Protection.

Note

Use version 1.02 or higher of the Client Connectivity Support Tool. Older versions report incorrect data for datacentre connectivity.

Example

To run the client connectivity support tool, execute the following from your client folder.


.\lch-support-win-64bit.exe


./lch-support-linux-64bit

Output


Luna Cloud HSM Support Tool 1.0.0-88451
------------------------------

Info
------------------------------
Serial Number:  *************
Hostname:       na.hsm.dpondemand.io

Checks
------------------------------
Validate client configuration file                                     PASS
Validate authentication server connection                              PASS
Validate authentication server certificate                             PASS
Validate issuer URL retrieval from authentication server               PASS
Validate token retrieval from authentication server                    PASS
Validate data center connection                                        PASS
Validate data center certificate                                       PASS

Errors
------------------------------
Note: For more detailed errors please run with --verbose

Errors

./setenv:24: = not found

The setenv command is only supported while using bash.

MSVCP140.dll Error

If you encounter the error MSVCP140.dll it means that your client host system is missing the Microsoft Visual C++ 2015 Redistributable Update 3 prerequisite. Refer to the section Luna Cloud HSM Services Supported Client Platforms for more details about required client prerequisites.

LUNA_RET_XTC_ERROR (80001600) Error

You may encounter the error DPoD:Unable to communicate with the service. Error code:LUNA_RET_XTC_ERROR (80001600) upon launching LunaCM or starting other applications against your Luna Cloud HSM Service. This indicates a problem with the Transferable Token Channel (XTC) connection to the HSM due to clock drift. Synchronize your client host with an NTP server and re-attempt a connection to your service. As part of normal operation, regularly and automatically synchronize to an NTP server as client operations rely on accurate time.

Caution

The host system's NTP time can overwrite a virtual machine's time clock, overwriting NTP in the virtual machine and applying the host system time. Failure to set the NTP or overwriting of the NTP in the virtual machine can make the client unable to access the HSM. Ensure the host system is using the correct time, or that the host system is not enforcing a time on the virtual machine.

CKR_MECHANISM_INVALID messages in mixed implementations

When using DPoD with a Luna Cloud HSM Service, you may encounter errors such as CKR_MECHANISM_INVALID or Error NCryptFinalizeKey during some operations in Hybrid HA and FIPS mode (3DES issue). This can occur if firmware versions differ between a Luna Network HSM partition and a Luna Cloud HSM Service in an HA group when you invoke a mechanism that is not supported by another member of the group. Similarly, if one member is in FIPS mode, while the other is not, a mechanism might be requested that is allowed for one member, but not the other. For example, the ms2luna tool can fail when 3DES operations are invoked.

Tip

For more information about FIPS and non-FIPS mode see the Luna Cloud HSM Service Guide.

CKR_PIN_EXPIRED Error

If you encounter the error CKR_PIN_EXPIRED, or if the function C_GenerateKeyPair returns 0xa3, it means that the crypto officer password was not changed following the initial log in.

When you create the crypto officer, you set a temporary password for the role. On first log in, you need to execute role changepw -name CO in order to update the password from the password that was set by the security officer.

If you are unable to log in to the crypto officer role, you need to re-initialize the crypto officer role and immediately reset the password. In LunaCM execute the following and respond to the prompts:

Note

You must be logged in as the partition Security Officer (PO) to initialize the crypto officer (CO) role.

  1. role init -name Crypto Officer

  2. role login -name CO

  3. role changepw -name CO

dll load failed with GetLast Error() 126

lunacm.exe will return the following error if:

  • the cvclient-min.zip or cvclient-min.tar folder contents are not extracted into the parent folder.
  • the setenv script has not been run.

dll load failed with GetLast Error() 126
trying to load [crystoNT.dll]
Cannot load library: The specified module could not be found

lunacm fails to connect with no error

lunacm.exe application can hang and fail to connect due to a misconfigured proxy file. Luna Cloud HSM Services communicate over HTTPS, as a result communications with Luna Cloud HSM Service require access to outgoing port 443 and DNS services.

If lunacm.exe hangs with the following, terminate the application with ctrl + c and verify your proxy configuration.


C:\Users\user\Desktop\service_client>lunacm
lunacm (64-bit) v10.1.0-32. Copyright (c) 2019 SafeNet. All rights reserved.

See Configuring a Client Proxy for more information on configuring your client proxy to work with the client.

CKR_MAX_SESSION_COUNT Error

New versions of the client disallow more mechanisms in FIPS mode than in previous versions, in keeping with NIST's updates to the FIPS standard. As a result, client applications that rely on these mechanisms can no longer operate in FIPS mode.

In general, 3DES, MAC, some key wrapping algorithms, and some key agreement algorithms are no longer allowed in FIPS mode. In addition, please see the Supported Mechanisms chapter in the SDK Guide for further details on FIPS support.

Clients which exceed the token object and session object limits can experience slow or failed request responses. The session limit is enforced, and the client receives the errors CKR_MAX_SESSION_COUNT when the application reaches the limit.

Generic Platform Error

Errors display an "incident ID". If you choose to contact your service provider for this error, note the incident ID and provide it to the service provider as it will assist the DPoD operations team in diagnosing the problem.

Failed to retrieve authentication token configuration from

If your network blocks all HTTP traffic the client connection to LunaCM will fail and return the error message Failed to retrieve authentication token configuration from <URL>. This error occurs because the Luna Cloud HSM Service is unable to access the HSM back end.

Ensure that Windows operating systems hosting the client are able to validate the server certificate status (OCSP/CRL) using port 80. HTTP traffic to the issuer of the SSL certificates must be permitted on the users network.

Common Error Messages

Authentication token retrieval failed with with error: 401 ({"error":"unauthorized","error_description":"Bad credentials"}) You are using the incorrect credentials to generate a JWT. Verify you are using the correct credentials for the operation you are tying to complete.

Cloud plugin: unable to fetch xtc certs The client authentication token cannot be validated. This error message can occur if:

  • The clients access to the service is revoked because the evaluation period has expired. Client access to the service is restored when you complete the Converting from Evaluation to Subscriber process.
  • The client 10.3 cannot connect to the Luna Cloud HSM Service due to the locale settings on the client machine. The following workarounds exist:
    • Change locale and display language to US English
      1. Go to Time & Language: Language in the Settings menu.
      2. Select English (United States) as the Windows display language.
      3. Go to Region: Administrative settings in the Control Panel and select Change system locale.
      4. Select English (United States) click OK.
    • Enable UTF-8 in locale settings
      1. Go to Region: Administrative settings in the Control Panel and select Change system locale.
      2. Select the Use Unicode UTF-8 checkbox and click OK.

DPoD: unable to fetch xtc certs The Luna Cloud HSM Service is unable to communicate with the datacenter. Verify your network connection, client configuration, and proxy configuration, then re-attempt your connection. See Configuring a Client Proxy for more information on configuring your client proxy to work with the client.

DPoD: unable to initialize XTC This indicates a problem with the Transferable Token Channel (XTC) connection to the HSM due to clock drift. Synchronize your client host with an NTP server and re-attempt a connection to your service. Client operations rely on accurate time.

Failed to initialize DPoD REST client: Failed to retrieve authentication token configuration from <tenant_address> The client is unable to communicate with the authentication server. Verify your network connection, client configuration, and proxy configuration, then re-attempt your connection. See Configuring a Client Proxy for more information on configuring your client proxy to work with the client.

Failed to initialize DPoD REST client: Failed to retrieve authentication token from <tenant_address> You are using the incorrect credentials to generate a JWT. Verify you are using the correct credentials for the operation you are tying to complete.https://thalesdocs.com/dpod/services/luna_cloud_hsm/extern/client_guides/Content

Please stand by while retrieving an authentication token from <tenant_address> You are using the incorrect credentials to generate a JWT. Verify you are using the correct credentials for the operation you are tying to complete.

Too many retries, giving up with RC_BUSY The client cannot connect to the partition. This error message can signify that the clients access to the service is revoked. Client access to the service is restored when you complete the Converting from Evaluation to Subscriber process.

Logging

You can configure the Luna Cloud HSM Service to provide additional logs in the application console by updating the crystoki.ini (Windows) or Chrystoki.conf (Linux) file, or manually setting the environment variables. Available logs include Application Error Logs and Curl Logs.

Logging can be enabled through shell session variables using set (Windows) and export (Linux). For more information about configuring persistent logging environment variables see Application Error Logs and Curl Logs.

To enable both log types and launch lunacm execute the following:


set AppLogLevel=info&set ShowCommands=1&set CurlLogsEnabled=True&set AppConsoleLogsEnabled=true&lunacm.exe


export AppLogLevel=info ShowCommands=1 CurlLogsEnabled=True AppConsoleLogsEnabled=true ;
./bin/64/lunacm 

Application Error Logs

Additional logs are displayed by default. If you wish to see more or less of these logs change the maximum severity level to be displayed by adding the environment variable AppLogLevel=<value>, using set (Windows) or export (Linux), or adding the following entry to the REST section of the Chrystoki.conf/crystoki.ini configuration file:


AppLogLevel=<value>

Valid Values:

  • trace (Unavailable for clients version 10.4 and newer)
  • debug (Unavailable for clients version 10.4 and newer)
  • error
  • warning
  • info

Windows: Windows operating systems print application error logs to the Event Viewer. Access the logs by opening Event Viewer > Windows Logs > Application and filtering the results for LunaClientEventProvider.

Note

To display Windows Logs in the Event Viewer as a non-administrator user you must register the LunaClientEventProvider.dll as described in Register LunaClientEventProvider.dll. Failure to register the LunaClientEventProvider.dll will result in the logs displaying to the console.

Linux: Linux operating systems print application error logs to /var/log/message. Access the logs by opening /var/log/message and searching the results for lunacm.

Ubuntu: If using Universal Client 10.4.1 Ubuntu operating systems print application error logs to /var/log/syslog. Access the logs by opening /var/log/syslog and searching the results for lunacm.

Curl Logs

Curl logs can be added to the console by adding the environment variable CurlLogsEnabled=True, using set (Windows) or export (Linux), or adding the following entry to the Rest section of the Chrystoki.conf/crystoki.ini configuration file:


CurlLogsEnabled=True

Note

You must have AppLogLevel=info defined in your Chrystoki.conf\crystoki.ini to retrieve curl logs. See Application Error Logs for more information about configuring AppLogLevel.

To disable Curl logs, update the environment variable or Chrystoki.conf/crystoki.ini configuration file to use CurlLogsEnabled=False.

If Curl Logs are enabled the output of the LunaCM command will begin with the following:


lunacm.exe (64-bit) v10.3.0-275. Copyright (c) 2020 SafeNet. All rights reserved.

* Uses proxy env variable no_proxy == '<proxy_environment_variable>'
*   Trying <IP_Address>...
* TCP_NODELAY set
* Connected to <tenant_URL> (<IP_Address>) port 443 (#0)
> POST /.well-known/openid-configuration HTTP/1.1
Host: <tenant_URL>
Content-Type: application/x-www-form-urlencoded
Accept: application/json
User-Agent: curl/7.35.0
Content-Length: 46

Windows: Windows operating systems print curl logs to the Event Viewer. Access the logs by opening Event Viewer > Windows Logs > Application and filtering the results for LunaClientEventProvider.

Note

To display Windows Logs in the Event Viewer as a non-administrator user you must register the LunaClientEventProvider.dll as described in Register LunaClientEventProvider.dll. Failure to register the LunaClientEventProvider.dll will result in the logs displaying to the console.

Linux: Linux operating systems print curl logs to /var/log/message. Access the logs by opening /var/log/message and searching the results for lunacm.

Ubuntu: If using Universal Client 10.4.1 Ubuntu operating systems print curl logs to /var/log/syslog. Access the logs by opening /var/log/syslog and searching the results for lunacm.

Testing Performance using Multitoken

The multitoken utility is a demonstration tool that can be used to test basic cryptographic functions on a Luna Cloud HSM. It allows you to specify an operation and the "slots" (partitions) on which to run the operation and returns a summary of the results.

To Access Multitoken

Note

You will need to initialize your Luna Cloud HSM before you can use multitoken.

  1. Open a command window.

  2. Go to the Luna Cloud HSM directory/folder.

  3. Launch multitoken.

    
    multitoken
    

You can run tests using the syntax multitoken -mode <mode> {-slots <slot_list> | -nslots <slot_threads>} [options...]

Note

A full list of multitoken operations can be found on the multitoken utility page.

Windows Operating Systems

If using a Microsoft Windows Server the server requires the following prerequisites to connect to the client: