Configuration File Summary

The Luna HSM Client software installation includes a configuration file that controls many aspects of client operation. The configuration file can be found in the following default locations:

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

>Linux/UNIX: /etc/Chrystoki.conf

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.

NOTE   Some of the sections/entries listed do not appear in the configuration file by default; you must add these sections/entries to change the behavior described below.

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

For Windows operations, the k7 driver cannot be signed when secure boot is enabled. The host machine will not allow functionality.

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 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 (G5)s 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 G7 Backup HSM slots reserved so that the library will check for connected devices.

Valid Values:

>0: If you have no Luna G7 Backup HSMs 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 via 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 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 appliance. It is controlled via an entry in the Luna HSM Client configuration file, and an equivalent file on the Luna Network HSM.

On the Luna Network HSM 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 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##
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 HSMs 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 partitions assigned to the client, which will always appear in the lowest-numbered slots, causing locally-connected and DPoD slots to increment higher.

ShowUserSlots

Allows you to set permanent slot numbers for specific partitions or HA virtual 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),...

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.

Misc
AppId = <xxx>

Application IDs are generated when the application starts, and are 16 bytes for Luna firmware 7.7.0 and compatible client software. 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.

CopyRSAPublicValues
FromPrivateTemplate

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.

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)

LoginAllowedOn
FMEnabledHSMs

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.

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

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 DPoD plugin to access DPoD Luna Cloud HSM services.

Default:

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

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

ProtectedAuthentication
PathFlagStatus

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)

NOTE   This remapping is automatic if you are using Luna HSM Client 10.1 or newer, and the configuration file entry is ignored.

RSAPre1863KeyGen
MechRemap

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   This remapping is automatic if you are using Luna HSM Client 10.1 or newer, and the configuration file entry is ignored.

ToolsDir

The location of the Luna HSM Client tools.

Default:

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

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

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

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 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 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 and your client application does proper housekeeping, or if your application is connecting via NTLS to a Luna Network HSM.

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 minimum firmware version 7.1.0.

lunacm_cv_ha_ui =

Controls whether Thales Data Protection on Demand's 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.1 or newer.

REST NOTE   This section is not created automatically for clients obtained from the Thales Support Portal. For such clients, this section must be copied from a DPoD Luna Cloud HSM service client configuration file (see Adding a Luna Cloud HSM Service). This section governs DPoD functionality only and is not related to the Luna REST API. This functionality requires Luna HSM Client 10.1 or newer.
ClientConnectIntervalMs

Interval in milliseconds between client connection attempts.

Default: 1000

ClientConnectRetryCount

Maximum connection attempts between the client and a Luna Cloud HSM service.

Default: 900

ClientEofRetryCount

Maximum command retries.

Default: 15

ClientPoolSize

Number of threads in the thread pool available for client operations. This entry does not apply to Luna HSM Client 10.2 and newer -- the pool size for these clients is always 64. If the number of parallel connections is more than 64, old connections are closed to make space in the cache.

Default: 32

ClientTimeoutSec

Time (in seconds) that the client waits for a response from a Luna Cloud HSM service. This timeout applies to each retry attempt individually.

Default: 120

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.

CurlLogsEnabled

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

Valid Values:

>0: Libcurl logging is disabled.

>1 (default): Libcurl logging is enabled.

CVAppSpecificData String containing identifying information about your Luna Cloud HSM service.
RestClient Indicates that Luna HSM Client and associated tools are acting as REST clients.
ServerName The name of the DPoD server providing Luna Cloud HSM services.
ServerPort The port used for DPoD server traffic.
SSLClientSideVerifyFile Location of the DPoD server certificate chain file (server-certificate.pem). This parameter applies to Luna HSM Client versions 10.1 and older.
XTC NOTE   This section is not created automatically for clients obtained from the Thales Support Portal. For such clients, this section must be copied from a DPoD Luna Cloud HSM service client configuration file (see Adding a Luna Cloud HSM Service). This functionality requires Luna HSM Client 10.1 or newer.
Enabled

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

Valid Values:

>0: XTC is disabled.

>1 (default): XTC is enabled.

PartitionCAPath Location of the Luna Cloud HSM service partition origin certificate (partition-ca-certificate.pem) for clients version 10.1 and older.
PartitionCertPath00 Location of the Luna Cloud HSM service partition messaging certificate (partition-certificate.pem) for clients version 10.1 and older.
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

XTC - CryptoVisor
Enabled

Indicates that XTC (Transferable Token Channel) is enabled.

Default: 1

TimeoutSec

Time in seconds for which a cryptographic request expires. Timestamps are included in XTC headers,

and the HSM rejects messages which have expired.

The valid range is 1-600 inclusive, and the value must be an integer.

Default: 600

PartitionCAPath Location of the partition origin certificate.
PartitionCertPath00 Location of the partition messaging certificate.

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