Configuration File Summary

The Luna HSM Client software installation includes a configuration file that controls many aspects of client operation. The fields in the configuration file are used to alter the default behavior of the library. So the default value is the value that would result in the normal (non-altered) behavior (but see TIP below). The configuration file can be found in the following default locations:

>Luna HSM Client

Windows: C:Program Files\SafeNet\LunaClient\crystoki.ini

Linux/UNIX: /etc/Chrystoki.conf

>Luna Cloud HSM

Windows: <service_client_path>\crystoki.ini

Linux: <service_client_path>/Chrystoki.conf

NOTE   The crystoki.ini and Chrystoki.conf files included with the Luna Cloud HSM service client provide a default set of configuration options. The setenv executable assists with the basic configuration requirements for communicating with the Luna Cloud HSM service.

The configuration file is organized into named sections, containing various configuration entries. It is installed with the default settings described in the table below. In addition to the default sections and entries, some additional sections/entries can be added to customize functionality. Generally, Thales does not recommend editing the configuration file directly; many entries are changed by entering commands in LunaCM or vtl. However, some entries can only be edited manually.

If you update the Luna HSM Client software by running the uninstaller and then installing a newer version, the existing configuration file is saved. This preserves your configuration settings, including the location of certificates necessary for your partition NTLS/STC connections for Luna products.

The following table describes all valid sections and entries in the configuration file. When editing the file, ensure that you maintain the applicable syntax conventions for your operating system (use existing sections/entries as a template for new entries). Where applicable, entries are listed with the valid range of values and the default setting.

TIP   Configuration settings and Section Headings

Some of the sections and entries listed here do not appear in the base configuration file as you would receive it via download; in many use-cases, your application's employment of the HSM would not require any direct intervention in the configuration file. "Factory" settings would be sufficient. If an application would benefit from a setting that differs from the stock values, and a visible entry is not already in the configuration file on your host system, then you must add a relevant entry in order to change the behavior described in the table below.

>If the configuration file contains no explicit entries that would reside under a particular heading, then the heading itself would also not be present.

>If you intend to add a setting to the file, and there is no pre-existing section-heading for it, then create a heading as indicated in the table, below, following the format of the other sections in your config file, appropriate for the host operating system (Linux/UNIX or Windows).

The majority of fields are Boolean (true/false or 0/1), or a range of values.

Some of the entries listed include a default setting that is observed if the entry is not included in the configuration file by default; you must add the entry explicitly, only in the case where you need to change the default behavior.

Exceptions:

>If an explicit location is not set for the library location (which is normally inserted as part of installation if you use the Client installer), or if you moved the library after a path value was included, an error message is generated about the field/path/file not being found, and you must provide a proper library location in order to proceed.

>If you intend to use an NTLS connection (Luna Network HSM 7) or an XTC connection (Luna Cloud HSM), then the relevant settings must be present to define that connection, or the connection does not take place.

Do not edit the Chrystoki.conf or crystoki.ini file unless you need to do so. If you need to edit, refer to the guidance in the table below, and ask for help from our technical support engineers if this document is not sufficient.

Section/Setting Description
Chrystoki2
LibNT

Path to the Chrystoki2 library on Windows operating systems.

Default: C:\Program Files\SafeNet\LunaClient\cryptoki.dll

LibNT32

Path to the Chrystoki2 library on 32-bit Windows systems only.

Default: C:\Program Files\SafeNet\LunaClient\win32\libCryptoki2.dll

NOTE   Luna HSM Client 10.1.0 and newer includes libraries for 64-bit operating systems only.

LibUNIX64

Path to the Chrystoki2 library on 64-bit Linux/UNIX operating systems.

Default:

>Linux/AIX: /usr/safenet/lunaclient/libs/64/libCryptoki2_64.so

>Solaris: /opt/safenet/lunaclient/libs/64/libCryptoki2_64.so

Luna (see * below this table)
CloningCommandTimeout

The amount of time (in milliseconds) the library allows for the HSM to respond to a cloning command.

Default: 300000

CommandTimeoutPedSet

This is an exception to DefaultTimeout (below). It defines the time (in milliseconds) allowed for all PED-related HSM commands. PED-related commands can take longer than ordinary commands governed by DefaultTimeOut.

Generally, the following formula applies:

CommandTimeOutPedSet = DefaultTimeOut + PEDTimeout1 + PEDTimeout2 + PEDTimeout3

Default: 720000

DefaultTimeOut

Defines the time (in milliseconds) the HSM driver in the host system waits for HSM commands to return a result. If a result is not returned in that time, the driver halts the HSM and returns DEVICE_ERROR to all applications using the HSM. The only exceptions are when a command's timeout is hard-coded in the Cryptoki library, or the command falls into a class governed by one of the other timeout intervals described elsewhere in this section.

Default: 500000

DomainParamTimeout

Timeout (in milliseconds) for Domain Parameter Generation.

Default: 5400000

KeypairGenTimeOut

Defines the time (in milliseconds) the library waits for a keypair generation operation to return a value. The randomization component of keypair generation can cause large keypairs to take a long time to generate, and this setting keeps the attempts within a reasonable time. You can change this value to manage your preferred balance between long waits and the inconvenience of restarting a keygen operation.

Default: 2700000

PEDTimeout1

Defines the time (in milliseconds) the HSM attempts to ping the PED before sending a PED operation request. If the PED is unreachable, the HSM returns a code indicating that the PED is not connected.

Default: 100000

PEDTimeout2

Defines the time (in milliseconds) that the HSM waits for the local PED to respond to a PED operation request. If the local PED does not respond to the request within the span of PEDTimeout2, the HSM returns an appropriate result code (such as PED_TIMEOUT). This is the timeout you might increase from the Default value if you were initializing larger MofN PED Key sets - the HSM allows M and N to each be up to 16 splits - maybe applying PED PINS, and making a duplicate set as well.

Default: 200000

PEDTimeout3

Defines the additional time (in milliseconds) the HSM waits for a remote PED to respond to a PED operation request. Therefore, the actual time the firmware waits for a remote PED response is PEDTimeout2 + PEDTimeout3.

Default: 20000

CardReader
LunaG5Slots

Number of Luna Backup HSM G5 slots reserved so that the library will check for connected devices.

Valid Values:

>0: If you have no Luna Backup HSM G5s and wish to eliminate the reserved spaces in your slot list, use this setting.

>1-N: Can be set to any number, but is effectively limited by the number of external USB devices supported by your client workstation.

Default: 3

LunaG7Slots

Number of Luna Backup HSM 7 slots reserved so that the library will check for connected devices.

Valid Values:

>0: If you have no Luna Backup HSM 7s and wish to eliminate the reserved spaces in your slot list, use this setting.

>1-N: Can be set to any number, but is effectively limited by the number of external USB devices supported by your client workstation.

Default: 3

RemoteCommand

This setting was used when debugging older Luna products. For modern products it is ignored.

Valid Values:

>0: false

>1 (default): true

CKLog2
NOTE See Using CKlog. Config is done using the vtl utility or by editing this config file directly.
RBS NOTE   RBS is not supported with Luna Cloud HSM services.
CmdProcessor

The location of the RBS library.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\rbs_processor2.dll

>Linux/AIX: /usr/safenet/lunaclient/rbs/lib/librbs_processor2.dll

>Solaris: /opt/safenet/lunaclient/rbs/lib/librbs_processor2.dll

HostPort

The port number used by the RBS server.

Valid Values: any unassigned port

Default: 1792

ClientAuthFile

The location of the RBS Client authentication file.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\config\clientauth.dat

>Linux/AIX: /usr/safenet/lunaclient/rbs/clientauth.dat

>Solaris: /opt/safenet/lunaclient/rbs/clientauth.dat

ServerSSLConfigFile

The location of the OpenSSL configuration file used by RBS Server or Client.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\rbs\server.cnf

>Linux/AIX: /usr/safenet/lunaclient/rbs/server/server.cnf

>Solaris: /opt/safenet/lunaclient/rbs/server/server.cnf

ServerPrivKeyFile

The location of the RBS Server certificate private key file.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\cert\server\serverkey.pem

>Linux/AIX: /usr/safenet/lunaclient/rbs/server/serverkey.pem

>Solaris: /opt/safenet/lunaclient/rbs/server/serverkey.pem

ServerCertFile

The location of the RBS Server certificate file.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\cert\server\server.pem

>Linux/AIX: /usr/safenet/lunaclient/rbs/server/server.pem

>Solaris: /opt/safenet/lunaclient/rbs/server/server.pem

NetServer

Determines whether RBS acts as a server or client.

Valid Values:

>0: Client

>1 (default): Server

HostName

The hostname or IP address that the RBS server will listen on.

Valid Value: any hostname or IP address

Default: 0.0.0.0 (any IP on the local host)

Available Lists the serial numbers of Luna Backup HSMs available on the RBS server.
LunaSA Client
ReceiveTimeout

Time in milliseconds before a receive timeout.

Default: 20000

SSLConfigFile

Location of the OpenSSL configuration file.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\openssl.cnf

>Linux/AIX: /usr/safenet/lunaclient/bin/openssl.cnf

>Solaris: /opt/safenet/lunaclient/bin/openssl.cnf

ClientPrivKeyFile

Location of the client private key. This value is set by vtl or lunacm:> clientconfig deploy.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\cert\client\<ClientName>Key.pem

>Linux/AIX: /usr/safenet/lunaclient/cert/client/<ClientName>Key.pem

>Solaris: /opt/safenet/lunaclient/cert/client/<ClientName>Key.pem

ClientCertFile

Location of the client certificate that is uploaded to Luna Network HSM 7 for NTLS. This value is set by vtl or lunacm:> clientconfig deploy.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\cert\client\<ClientName>Cert.pem

>Linux/AIX: /usr/safenet/lunaclient/cert/client/<ClientName>Cert.pem

>Solaris: /opt/safenet/lunaclient/cert/client/<ClientName>Cert.pem

ServerCAFile

Location of the server certificate file on the client workstation. This value is set by vtl or lunacm:> clientconfig deploy.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\cert\server\CAFile.pem

>Linux/AIX: /usr/safenet/lunaclient/cert/server/CAFile.pem

>Solaris: /opt/safenet/lunaclient/cert/server/CAFile.pem

NetClient

Determines whether the library searches for network slots.

Valid Values:

>0: The library does not search for network slots.

>1 (default): The library searches for network slots.

TCPKeepAlive

TCPKeepAlive is a TCP stack option, available at the Luna HSM Client and the Luna Network HSM 7 appliance. It is controlled via an entry in the Luna HSM Client configuration file, and an equivalent file on the Luna Network HSM 7.

On the Luna Network HSM 7 appliance, where you do not have direct access to the file system, the TCPKeepAlive= setting is controlled by lunash:> ntls tcp_keepalive set.

The settings at the appliance and the client are independent. This allows a level of assurance, in case (for example) a firewall setting blocks communication in one direction.

Valid Values:

>0: false

>1 (default): true

ServerName##

These entries identify NTLS-linked Luna Network HSM 7 servers/ports, and determines the order in which they are polled to create a slot list. These values are set by vtl or lunacm:> clientconfig deploy.

ServerPort##
LNHServer## The IP address and port of a Luna Network HSM 7 cluster member connected to this client. See Cluster-Client Connections.
LNHServerClientCert## The location and filename of the Luna HSM Client certificate used to access this Luna Network HSM 7 cluster. See Cluster-Client Connections.
LNHServerClientKey## The location and filename of the Luna HSM Client private key used to access this Luna Network HSM 7 cluster. See Cluster-Client Connections.
LNHServerCAFile## The location and filename of the Luna Network HSM 7 cluster server certificate. See Cluster-Client Connections.
LNHServerCN## The Common Name for the cluster certificate. See Cluster-Client Connections.
Presentation NOTE   This section is not created automatically. To change any of the following values, you must first create this section in the configuration file.
OneBaseSlotId

Determines whether slot listing begins at 0 or 1.

Default: 0

ShowAdminTokens

Determines whether the Admin partitions of locally-installed Luna PCIe HSM 7s are visible in the slot list.

Valid Values:

>no: Admin slots are hidden.

>yes (default): Admin slots are visible.

ShowEmptySlots

Determines whether slot numbers are reserved for partitions that have not yet been created on the HSM. When this setting is enabled, slot numbers remain consistent over time, even when new partitions are created.

Valid Values:

>no (default): Only existing partitions are assigned slot numbers.

>yes: Slot numbers are reserved for the maximum number of partitions that can be created on HSMs connected to the client.

NOTE   This does not apply to Luna Network HSM 7 partitions assigned to the client, which will always appear in the lowest-numbered slots, causing locally-connected and Luna Cloud HSM service slots to increment higher.

ShowUserSlots

Allows you to set permanent slot numbers for specific partitions. If you use this setting, you must specify a slot for all partitions on a specific HSM, or the partitions not listed here will not be visible to the client.

Valid Values: Comma-delimited list in the format <slotnum>(<serialnum>)

Example:

ShowUserSlots=1(351970018022),2(351970018021),3(351970018020),...

VirtualToken NOTE   This section is created only if the HA auto-recovery mode is set to activeEnhanced. See Configuring HA Auto-Recovery.
VirtualToken##Label

The label of the HA group.

This value is set by using the lunacm:> hagroup creategroup command to set up an HA group. See Setting Up an HA Group.

VirtualToken##SN

The pseudo serial number of the HA group.

This value is set by using the lunacm:> hagroup creategroup command to set up an HA group. See Setting Up an HA Group.

VirtualToken##Members

The serial number of the HA group members.

This value is set by using the lunacm:> hagroup addmember command to add a member to the HA group. See Setting Up an HA Group.

VirtualTokenActiveRecovery

The HA auto-recovery mode.

This value is set by using the lunacm:> hagroup recoverymode command to configure the HA auto-recovery mode. See Configuring HA Auto-Recovery.

HAConfiguration
AutoReconnectInterval

Specifies the interval (in seconds) at which the library will attempt to reconnect with a missing HA member, until the set number of attempts is reached. This value is set using lunacm:> hagroup interval.

Valid Values:

>60-1200: Wait the specified number of seconds between reconnection attempts.

Default: 60 seconds

HAOnly

Determines whether individual HA member slots are visible to client applications. Hiding individual members helps prevent synchronization errors by preventing applications from directing calls to individual member partitions. If a member partition fails, the other slots in the system change, which can cause applications to send calls to the wrong slot number. This setting prevents this by hiding all physical slots from applications.

Valid Values:

>0 (default): All partitions are visible to applications as slots.

>1: Only HA virtual slots are visible to applications.

NOTE   This setting does not affect how slots are numbered in LunaCM; you can still configure individual member partitions with HAOnly mode enabled.

reconnAtt

Specifies the number of reconnection attempts the client makes to a missing HA member. Once this number is reached, you must manually reconnect the member when it becomes available (see Manually Recovering a Failed HA Group Member).

This value is set using lunacm:> hagroup retry.

Valid Values:

>-1: Perform infinite reconnection attempts.

>0: Disable HA auto-recovery.

>1-500: Perform the specified number of reconnection attempts.

statusTimeout

This value (in seconds) is the amount of time the CA_GetCurrentHAState function will try to verify the status of HA group members, before stopping and reporting the statuses collected up to that cutoff.

Valid Values:

>3 (default): This is the shortest reasonable value in good network conditions.

>4-60: Any value between the default and 60 second.

NOTE   After 60 seconds, the status check could conflict with other processes, so the cap is set at 60.

Misc
AppId = <xxx>

Application IDs are generated when the application starts, and are 16 bytes for Luna HSM Firmware 7.7.0 and newer, and and Luna HSM Client 10.3.0 and newer. Application IDs are not supported for Luna Cloud HSM services. For earlier HSM firmware or clients, see Application IDs. You can override this functionality and specify an AppId if desired.

CopyRSAPublicValuesFromPrivateTemplate

Controls whether the public exponent of an RSA key can be copied from the private key template, if the public key template does not already have a public exponent attribute set.

Valid Values:

>0: if no public exponent is provided in the public template, an error is returned (expected behavior).

>1(default): if no public exponent is provided in the public template, the private exponent is copied from the private template to populate the public template.

For PKCS#11 compliance, this should be set to 0.

NOTE   This functionality requires Luna HSM Client 7.1.0 or newer.

ECCPointEncodingStrategy=

Allows you to force (or not) the assumption that an Elliptic Curve point is provided in RAW octet string format.

Valid Values:

>1: Queries HSM for correct EC Point Size, then determines whether encoding is required or not.

>2: Does not query the HSM for EC point size. Assumes EC point is RAW and always encodes it.

(Included in client since Luna HSM Client  10.5.0; available as a patch for Luna HSM Client 10.4.0 and 10.4.1. Beginning with HSM firmware version 7.8.1 this entry is no longer needed.)

FunctionBindLevel

Determines what action to take if a function binding fails during a CryptokiConnect() operation.

Valid Values:

>0 (default): fail if not all functions can be resolved

>1: do not fail but issue warning for each function not resolved

>2: do not fail and do not issue warning (silent mode)

LoginAllowedOnFMEnabledHSMs

Determines whether the client can log in to a partition on an HSM that uses Functionality Modules (FMs). FMs consist of custom-designed code that introduces new functionality, which can be more or less secure than standard HSM functions.

Possible values include:

>0: the client does not allow login to an FM-enabled partition

>1: the client allows login to an FM-enabled partition

This entry is added to the configuration file the first time you initialize or log in to an FM-enabled partition using LunaCM. You are prompted to confirm that you want to allow login.

MutexFolder=

For non-Windows platforms. Several Luna features write temporary files to /tmp. If systemd service deletes the temporary files the affected services can be disrupted - example Remote PED callback service (cbs). An administrator can use this setting to specify an alternative location like this example:

Misc = {
…
  MutexFolder = /usr/lock;
}

The specified folder must exist, or the service fails to start properly.

>Linux default: <install_dir>/lock

PE1746Enabled

Enables the SafeXcel 1746 security co-processor on Luna 6 HSMs, which is used to offload packet processing and cryptographic computations from the host processor. Does not apply to Luna 7 HSMs or Luna Cloud HSM services. This must be set to 0 to use Luna 6 partitions in a mixed-version HA group (see Cloning Keys Between Luna 6, Luna 7, and Luna Cloud HSM, Password or Multifactor Quorum).

Valid Values:

>0: SafeXcel co-processor is disabled on Luna 6 HSMs.

>1 (default): SafeXcel co-processor is enabled on Luna 6 HSMs.

PluginModuleDir

Specifies the location of client plugins. This setting is required to use the cloud plugin to access Luna Cloud HSM services.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\plugins

>Linux: /usr/safenet/lunaclient/libs/64/plugins

ProtectedAuthenticationPathFlagStatus

Specifies which role to check for challenge request status.

Valid Values:

>0 (default): no challenge request

>1: check for Crypto Officer challenge request

>2: check for Crypto User challenge request

NOTE   This functionality requires Luna HSM Client 7.1.0 or newer.

RSAKeyGenMechRemap

This entry remaps calls to certain older mechanisms, no longer supported on the latest firmware, to use newer, more secure mechanisms instead.

>0: No re-mapping is performed.

>1: The following re-mapping occurs:

PKCS Key Gen -> 186-3 Prime key gen

X9.31 Key Gen -> 186-3 Aux Prime key gen (see Mechanism Remap for FIPS Compliance)

Mechanism remapping is automatic, and ignores the configuration file entry if:

>you are using Luna HSM Client 10.1.0 or newer, and

>HSM firmware is older than Luna HSM Firmware 7.7.1 (which introduced FIPS mode on individual partitions; clients up to and including Luna HSM Client 10.3.0 are unaware of the independent partition setting and do not remap mechanisms).

Luna HSM Client 10.4.0 and newer are aware of the change in Luna HSM Firmware 7.7.1 and perform the mechanism remapping as expected when the current partition is in FIPS mode.

RSAPre1863KeyGenMechRemap

This entry remaps calls to newer mechanisms, when they are not available on older firmware, to use older mechanisms instead. Intended for evaluation purposes, such as with existing integrations that require newer mechanisms, before you update to firmware that actually supports the more secure mechanisms. Be careful with this setting, which makes it appear you are using a new, secure mechanism, when really you are using an outdated, insecure mechanism (see Mechanism Remap for FIPS Compliance).

>0: No re-mapping is performed.

>1: The following re-mapping occurs if the HSM firmware permits:

186-3 Prime key gen -> PKCS Key Gen

186-3 Aux Prime key gen -> X9.31 Key Gen

NOTE   Mechanism remapping is automatic, and ignores the configuration file entry if:

>you are using Luna HSM Client 10.1.0 or newer, and

>HSM firmware is older than Luna HSM Firmware 7.7.1 (which introduced FIPS mode on individual partitions; clients up to and including Luna HSM Client 10.3.0 are unaware of the independent partition setting and do not remap mechanisms).

Luna HSM Client 10.4.0 and newer are aware of the change in Luna HSM Firmware 7.7.1 and perform the mechanism remapping as expected when the current partition is in FIPS mode.

ToolsDir

The location of the Luna HSM Client tools.

Full Luna HSM Client Default:

>Windows: C:\Program Files\SafeNet\LunaClient\

>Linux/AIX: /usr/safenet/lunaclient/bin/

>Solaris: /opt/safenet/lunaclient/bin/

Minimal Luna HSM Client Default:

>Linux: /usr/safenet/lunaclient/bin/64/

ValidateHost=

Set this flag to have the Luna HSM Client validate the server's hostname/IP against the Subject Alternate Name (SAN) values in the server's certificate.

Default: 0

Secure Trusted Channel NOTE   Secure Trusted Channel is not supported with Luna Cloud HSM Services.
ClientIdentitiesDir

Specifies the directory used to store the STC client identity.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\data\client_identities

>Linux/AIX: /usr/safenet/lunaclient/data/client_identities

>Solaris: /opt/safenet/lunaclient/data/client_identities

ClientTokenLib

(for 64-bit Windows systems)

Specifies the location of the token library on 64-bit Windows systems. This value must be correct in order to use a client token. If you are using a hard token, you must manually change this value to point to the hard token library for your operating system. The exact location of the hard token library may vary depending on your installer.

Default: C:\Program Files\SafeNet\LunaClient\softtoken.dll

ClientTokenLib32

(for 32-bit Windows systems)

Specifies the location of the token library on 32-bit Windows systems. This entry appears on Windows only.

By default, ClientTokenLib32 points to the location of the soft token library. If you are using a hard token, you must manually change this value to point to the hard token library for your operating system. The exact location of the hard token library may vary depending on your installer.

Soft Token Default: C:\Program Files\SafeNet\LunaClient\win32\softtoken.dll

Hard Token Default: C:\Windows\SysWOW64\etoken.dll

NOTE   Luna HSM Client 10.1.0 and newer includes libraries for 64-bit operating systems only.

PartitionIdentitiesDir

Specifies the directory used to store the STC partition identities exported using lunacm:> stcconfig partitionidexport.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\data\partition_identities

>Linux/AIX: /usr/safenet/lunaclient/data/partition_identities

>Solaris: /opt/safenet/lunaclient/data/partition_identities

SoftTokenDir

Specifies the location where the STC client soft token (token.db) is stored.

Default:

>Windows: C:\Program Files\SafeNet\LunaClient\softtoken\001\

>Linux/AIX: /usr/safenet/lunaclient/softtoken/001/

>Solaris: /opt/safenet/lunaclient/softtoken/001/

Session NOTE   This section is not created automatically. To change any of the following values, you must first create this section in the configuration file.
AutoCleanUpDisabled

Determines whether AutoCleanUp closes orphaned sessions in the event that an application leaves sessions open. Useful for Luna PCIe HSM hosts. AutoCleanUp runs during C_Finalize on the client. Luna Network HSM 7 sessions are tracked and closed by the NTLS service.

Valid Values:

>0 (default): Run AutoCleanUp if your application leaks sessions and you cannot rewrite the application.

>1: Disable AutoCleanUp if you have a Luna PCIe HSM 7 and your client application does proper housekeeping, or if your application is connecting via NTLS to a Luna Network HSM 7.

Shim2 NOTE   This section is not created automatically. To change any of the following values, you must first create this section in the configuration file.

(Linux)
LibUNIX64=/usr/safenet/lunaclient/lib/libCryptoki2_64.so;

(Windows)
LibNT=C:\Program Files\SafeNet\LunaClient\cryptoki.dll

This section is required when a shim is to be used.

If the cryptoki library is not at the indicated location, then adjust the example path value to reflect the actual location.

Toggles NOTE   This section is not created automatically. To change any of the following values, you must first create this section in the configuration file.
legacy_memory_rep =

Controls the manner in which the HSM reports the available RAM space.

Valid Values:

>0 (default): the public and private memory total/free values reported in the CK_TOKEN_INFO structure indicate the available flash memory for permanent (TOKEN) objects that are in either the public or private space respectively; this method is PKCS#11 compliant.

>1: the public memory values indicate the total/free RAM memory; this non-standard legacy method was used by some customers to determine space available for session based objects, and must be explicitly selected in order to continue using the legacy method.

NOTE   This functionality requires Luna HSM Firmware 7.1.0 or newer.

lunacm_cv_ha_ui =

Controls whether Thales DPoD Luna Cloud HSM services can be active members of an HA group.

Valid Values:

>0: Luna Cloud HSM services can be added as active HA members.

>1 (default): Luna Cloud HSM services can be added to HA groups as standby members only. This is the default behavior to maximize HA performance, which may suffer due to network latency.

NOTE   This functionality requires Luna HSM Client 10.2.0 or newer.

fetch_partition_label =

Allows the client to refresh the slot list without requiring an application restart.

Valid Values:

>0 (default): A new session must be opened (C_Initialize) to refresh the slot list cache.

>1: Slot list cache is refreshed without requiring C_Initialize.

NOTE   This functionality requires Luna HSM Client 10.5.1 or newer.

map_aes_cmac_general_old=

Allows the library to automatically map relevant values to the required mechanism CKM_AES_CMAC_GENERAL. Refer to resolved issue LUNA-30232.

NOTE   This functionality requires Luna HSM Client 10.7.0 or newer.

REST

NOTE   This section configures a connection to a Luna Cloud HSM and applies only to a Luna Cloud HSM. This section is not created automatically for clients obtained from the Thales Support Portal. See Adding a Luna Cloud HSM Service for detailed instructions on adding a Luna Cloud HSM service client to a Luna HSM Client.

This section governs Luna Cloud HSM service functionality only and is not related to the Luna REST API. This functionality requires Luna HSM Client 10.2.0 or newer.

AppLogLevel

Defines the maximum severity level of application logs to be displayed in the application console.

Valid Values:

>trace (unavailable for Luna HSM Client 10.4.0 and newer)

>debug (unavailable for Luna HSM Client 10.4.0 and newer)

>error (default setting for Luna HSM Client 10.2.0 and Luna HSM Client 10.3.0)

>warning

>info

Application Error Logs are printed to the Event Viewer on Windows 10 and to the system and console on Linux.

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

AuthTokenConfigURI The identifier for the authentication service which issues the tokens required to validate the client's identity to the Luna Cloud HSM service. Your client host must have an internet connection to reach this resource. Do not edit the default value unless instructed to by customer support.
AuthTokenClientId The client identity required by the authentication service to issue a token. Do not edit the default value unless instructed to by customer support.
AuthTokenClientSecret The client passphrase required by the authentication service to issue a token. Do not edit the default value unless instructed to by customer support.
CurlLogsEnabled

Enables libcurl logging. This variable applies to Luna HSM Client 10.3.0 and newer.

Valid Values:

>False:Libcurl logging is disabled.

>True(default): Libcurl logging is enabled.

NOTE   If using Luna HSM Client 10.4.0 or newer you must have AppLogLevel=info defined in your Chrystoki.conf\crystoki.ini to retrieve curl logs. See AppLogLevel for more information.

Curl Logs are printed to the Event Viewer on Windows 10 and to the system and console on Linux.

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

ClientConnectIntervalMs

Interval in milliseconds between client connection attempts.

Default: 1000

ClientConnectRetryCount

Maximum connection attempts between a client and a server.

Default: 900

ClientEofRetryCount

Maximum command retries.

Default: 15

ClientPoolSize

Number of threads in the thread pool available for client operations.

Default: 32

ClientTimeoutSec

Time in seconds that a client waits for a response. This timeout applies to each retry attempt individually.

Default: 600

NOTE   This entry does not appear in the default configuration file, but the default value applies to this timeout. You can manually add the entry if you wish to edit the timeout.

PartitionData00

The partition serial number, load balancer IP address or hostname, and load balancer port.

Executing setenv, when configuring the Luna HSM Client, removes PartitionData00 and replaces it with values for ServerName and ServerPort.

The following format is used:

PartitionData00=<partition_serial_number>, <service_ip_address/hostname>, <service_port>;

CAUTION!   The Luna Cloud HSM service failover to the redundant datacenter uses a change to DNS to direct client traffic to a secondary datacenter. The client configuration file includes the FQDN for the Luna Cloud HSM service datacenter in the REST = PartitionData00 section or the REST = ServerName section after executing setenv (eu.hsm.dpondemand.io or na.hsm.dpondemand.io). In the event of a failover the DNS record for FQDN is updated to point to the secondary datacenter.

Ensure that the client is configured to use the domain name for the datacenter and to not configure any filtering based on the IP addresses. Failure to use the domain name and filtering IP addresses could result in the client being unable to failover to the secondary datacenter.

RestClient

Indicates that cvclient and associated tools are acting as REST clients.

Default: 1

ServerName The name of the Luna Cloud HSM server.
ServerPort The port used for Luna Cloud HSM server traffic.
XTC

NOTE   This section configures a connection to a Luna Cloud HSM and applies only to a Luna Cloud HSM. This section is not created automatically for clients obtained from the Thales Support Portal. See Adding a Luna Cloud HSM Service for detailed instructions on adding a Luna Cloud HSM service client to a Luna HSM Client.

This section governs Luna Cloud HSM service functionality only and is not related to the Luna REST API. Requires Luna HSM Client 10.2.0 or newer.

Enabled

Indicates that XTC (Transferable Token Channel) is enabled. This channel must be enabled for the client to communicate with a Luna Cloud HSM service.

Valid Values:

>0: XTC is disabled.

>1 (default): XTC is enabled.

TimeoutSec

Time (in seconds) before a cryptographic request expires. Timestamps are included in XTC headers, and the HSM rejects messages which have expired.

Valid Values: 1-600

GemEngine NOTE   This section is not created automatically.
DisableCheckFinalize

Determines how the gem engine behaves for finalizing the cryptoki library. If an application has forking processes, then this causes the connection with the HSM to be shared between the parent and the child process which must be addressed for Linux/UNIX.

Valid Values:

>0 (default): Perform pre-fork checking -- when crypto calls are made in the parent process, the cryptoki library is finalized after each crypto call. However, in the child process, the library is initialized and the connection to the HSM is maintained after crypto calls. The parent and child will have different connections to the HSM.

>1: Perform post-fork checking -- the engine initializes the cryptoki library and maintains the connection to the HSM until the application terminates.

If your application (own or 3rd party) is using OpenSSL and has forking processes, set this value to 0. Otherwise, setting the option to 1 will improve performance.

Not used for Windows.

* If you intend to invoke a large number N for an M of N keyset (maximum is 16 splits), including also a backup set, you will need to increase the various PED timeout values well beyond the default values, in order to have enough time to comfortably complete the task. As a rough example, increase the PED's timeout for creating a keyset by a factor of 10. Altogether, the combined value works out to:

CommandTimeOutPedSet  >= ( DefaultTimeOut + PEDTimeout1 + PEDTimeout2 + PEDTimeout3 ) 

So, for example, in the Luna section of the .conf file (similar for the .ini file in Windows): 

Luna =  
{ DefaultTimeOut = 500000; PEDTimeout1 = 100000; PEDTimeout2 = 2000000; PEDTimeout3 = 20000; KeypairGenTimeOut = 2700000; CloningCommandTimeOut = 300000; CommandTimeOutPedSet = 2620000; }

The longest such activity would be creating a 16-key split of a new-format orange PED Key (RPK), with duplicates, which might take a little more than half an hour at a comfortable pace with no interruptions. This is considered an extreme edge-case. Your situation will probably require settings somewhere between the defaults and the values suggested above.  

Dynamic UserID Loading for Luna Cloud HSM Services

The UC Dynamic Loading feature is introduced in Luna HSM Client 10.5.0 for Luna Cloud HSM services. This allows each User Account and Authentication (UAA) user to have the ability to have one or more partition(s) associated with them. The DPoD tenant role can now configure multiple UAA Users and manage them in one place instead of managing each one separately. This will also allow customers to add multiple UserID's (combination of unique authtokenclientsecret, authtokenclientid and URI) without the need to restart the application after the addition of a new UserID.

The ability to load multiple partitions to the same UserID without impacting service to other users is also supported. If an attempt is made to add the same partition ID to a different user that will be ignored and a warning log will be generated.

When a new configuration is added, running the "slot list" command will display the new partition ID for that user.

NOTE   The maximum amount of users to be added using the "MaxUserIDCount" variable is defaulted at 100. Multiple partitions for the same user will NOT have a sequential slot ID.

In Linux:

export AuthtokenConfigURI2=***********
export AuthTokenClientID2=**********
export AuthTokenClientSecret2=***********
 
export AuthtokenConfigURI3=***********
export AuthTokenClientID3=**********
export AuthTokenClientSecret3=***********

In Windows:

set var=AuthTokenConfigURI2=***********
set var=AuthTokenClientID2=**********
set var=AuthTokenClientSecret2=***********
 
set var=AuthTokenConfigURI3=***********
set var=AuthTokenClientID3=**********
set var=AuthTokenClientSecret3=***********