Troubleshoot 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 systems client connection to the Luna Cloud HSM Service. The lch-support-linux64bit (Linux) and lch-support-win-64bit (Windows) is included in the client package downloaded for 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 in the console run the tool with --verbose.

The timing for each validation step is tracked and recorded in the output. If a validation step takes more than 15s there is a connection error and LunaCM may take up to 15 minutes to timeout.

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

The client connectivity support tool generates a detailed debug log file with the label Support-Tool-Output.<datestamp>.<timestamp>.txt in the client folder. The regular support tool output is put in this file as well as additional logging generated by running lunacm. Please include this generated debug log file in communications with Thales support when troubleshooting your client connection.

Example

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

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

./lch-support-linux-64bit

Sample Failure Output

Luna Cloud HSM Support Tool 1.0.6-258880
------------------------------

Info
------------------------------
Proxy:          ********
Serial Number:  N/A
Hostname:       na-orch.hsm.dpod.live

Checks
------------------------------
Validate client configuration file                                     PASS 0ms
Validate authentication server connection                              PASS 2806ms
Validate authentication server certificate                             PASS 2176ms
Validate issuer URL retrieval from authentication server               PASS 2176ms
Validate token retrieval from authentication server                    FAIL 2374ms
Validate data center connection                                        SKIP 0ms
Validate data center certificate                                       SKIP 0ms

Errors
------------------------------
Got 401 status code from authentication server, response: {"error":"unauthorized","error_description":"Bad credentials"}
Got 401 status code from authentication server, response: {"error":"unauthorized","error_description":"Bad credentials"}

Debug file was successfully generated: Support-Tool-Output.2024-07-25.15-07-55.txt
Execution of lunacm took 43s 

There was an error using lunacm: exit status 1

System Troubleshooting

If the client connection is failing we recommend the following local troubleshooting:

• Download the most recent client from the tenant and reattempt the connection.
• Retry the connection from another system.
• Validate your systems DNS and TCP/443 access.
• Ensure that no proxies are tampering with certificates.
• If you are using a hosts file or static IP address use a tool, such as nslookup, to revalidate the IPs from another system.
• Review the recommendations in Client Network Connectivity.

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.

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.

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:

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 Purchase a Service Subscription.
• 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 Purchase a Service Subscription.

SEC_E_CERT_EXPIRED (0x80090328) error The client cannot connect to the partition. This error message states that the certificate being accessed is expired. We recommend investigating the use of hosts files or static IP filtering on your system. See Client Network Connectivity for more information.

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.

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

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.

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

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

Windows operating systems

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

• Microsoft Visual C++ 2015 Redistributable Update 3
• Universal C Runtime (CRT) Microsoft Visual C++ 2015 Redistributable Update 3 requires Universal C Runtime (CRT) to be installed. Older Windows versions may not have this installed. If not installed, you will get a "Setup Failed" error. If this occurs, you will need to install Universal C Runtime in Windows update, and its prerequisites.