Configuration File Summary
Many aspects of SafeNet Luna HSM configuration and operation are controlled or adjusted by the Chrystoki.conf file (Linux/UNIX) or Crystoki.ini file (Windows). The examples in the table below are from a Windows Chrystoki.ini file.
The configuration file is organized into named sections, under which related configuration-affecting entries might appear. A basic configuration file is always present in the SafeNet Luna Client folder, installed by the SafeNet Luna Client installer, with default values assigned to the populated entries. In addition to the most basic sections and entries, some additional sections and entries can be included at installation time, if you select more than the minimal installation options for your HSM model(s).
In addition, new entries can be added, or existing entries can be adjusted by actions that you perform in SafeNet tools like LunaCM and vtl.
Finally, some sections or entries can be added or adjusted by manual editing of the Chrystoki.conf /Crystoki.ini file.
If you install SafeNet Luna Client where a previous version was installed, then the existing configuration file is saved and the new file adds to the existing content if appropriate. That is, if you have a SafeNet Luna HSM setup, already configured and tweaked to your satisfaction, those settings are preserved when you update to newer SafeNet Luna Client.
The following table lists sections and settings that you are likely to encounter in normal use of SafeNet products. Not all are applicable to every SafeNet Luna HSM. Each setting is named, with default values, allowed range of values, description of the item/setting, and remarks about any interactions between the current setting and others that you might configure.
Where the range is a file path, <luna_client_dir> specifies the path to your SafeNet Luna HSM client installation.
| Setting | Range (Default) | Description |
|---|---|---|
|
|
||
|
LibNT= |
(<luna_client_dir>\cryptoki.dll) |
Path to the Chrystoki2 library. |
|
LibNT32= |
(<luna_client_dir>\win32\libCryptoki2.dll) |
Path to the Chrystoki2 library on 32-bit Windows systems only. |
|
|
||
|
PEDTimeout1= |
(100000) ms |
Specifies the PED timeout time 1 - defines how long (in milliseconds) the HSM tries to detect if it can talk to the PED before starting the actual communication with it. If the PED is unreachable the HSM returns to the host a result code for the respective HSM command. The result code indicates that the PED is not connected. This timeout is intended to be small so that the user is informed quickly that the PED is not connected. |
|
PEDTimeout2= |
(200000) ms |
Specifies the PED timeout time 2 - defines how long (in milliseconds) the firmware waits for the local PED to respond to PED commands. PED commands should not be confused with PED-related HSM commands. An HSM sends PED commands to the PED when processing PED-related HSM commands, such as LOGIN or PED_CONNECT. One PED-related HSM command can involve many PED commands being sent by the HSM to the PED (for example, the MofN related commands). If a local PED does not respond to the PED commands within the span of PEDTimeout2 the HSM returns an appropriate result code (such as PED_TIMEOUT) for the respective PED-related HSM command. |
|
PEDTimeout3= |
(20000) ms |
Specifies the PED timeout time 3 - defines additional time (in milliseconds) the firmware must wait for the remote PED to respond to PED commands. That is, the actual time the firmware waits for a remote PED to respond is PEDTimeout2 + PEDTimeout3. |
|
DefaultTimeOut= |
(500000) ms |
Sets the default timeout interval - defines how long (in milliseconds) the HSM driver in the host system waits for HSM commands to return a result code. If the result code is not returned in that time, the driver assumes that the HSM is stuck and halts it, with the DEVICE_ERROR returned to all applications that use the HSM. Most HSM commands use this timeout. Very few exceptions exist, when a command's timeout is hard-coded in the Cryptoki library, or separate timeouts are specified in the Chrystoki.conf for certain classes of HSM commands. |
|
CommandTimeoutPedSet= |
(720000) ms |
This is an exception to DefaultTimeout (above). It defines timeout (in milliseconds) for all PED-related HSM commands. This class of PED-related commands can take more time than the ordinary commands that subscribe to the DefaultTimeOut value. As a rule of thumb, CommandTimeOutPedSet = DefaultTimeOut + PEDTimeout1 + PEDTimeout2 + PEDTimeout3. |
|
KeypairGenTimeOut= |
(2700000) ms |
The amount of time (in milliseconds) the library allows for a Keypair generate operation to return a value. Due to the random component, large key sizes can take an arbitrarily long time to generate, and this setting keeps the attempts within reasonable bounds.The default is calculated as the best balance between the inconvenience of occasional very long waits and the inconvenience of restarting a keygen operation. You can change it to suit your situation. |
|
CloningCommandTimeout= |
(300000) ms |
The amount of time (in milliseconds) the library allows for the HSM to respond to a cloning command. |
|
DomainParamTimeout= |
(5400000) ms |
Timeout for Domain Parameter Generation. |
|
|
||
|
RemoteCommand= |
0 = false (1 = true) |
This setting was used when debugging older SafeNet products. For modern products it is ignored. |
|
LunaG5Slots= |
(3) |
Number of SafeNet Luna USB HSM slots reserved so that the library will check for connected devices. >Can be set to zero if you have no SafeNet Luna USB HSMs and wish to get rid of the reserved spaces in your slot list. >Can be set to any number, but is effectively limited by the number of external USB devices your host can support. |
|
|
||
|
HostName= |
Any hostname or IP address (0.0.0.0) |
The hostname or IP address that the RBS server will listen on. Default is 0.0.0.0 (any IP on the local host). |
|
HostPort= |
Any unassigned port(1792) |
The port number used by the RBS server. |
|
ClientAuthFile= |
(<luna_client_dir>\config\clientauth.dat) |
The location of the RBS Client authentication file. |
|
ServerCertFile= |
(<luna_client_dir>\cert\server\server.pem) |
The location of the RBS Server certificate file. |
|
ServerPrivKeyFile= |
(<luna_client_dir>\cert\server\serverkey.pem) |
The location of the RBS Server certificate private key file. |
|
ServerSSLConfigFile= |
(<luna_client_dir>\openssl.cnf) |
The location of the OpenSSL configuration file used by RBS Server or Client. |
|
CmdProcessor= |
(<luna_client_dir>\rbs_processor2.dll) |
The location of the RBS library. |
|
NetServer= |
0 = false (1 = true) |
If true (default), RBS acts as a Server. If false, RBS acts as a Client. |
|
|
||
|
SSLConfigFile= |
(<luna_client_dir>\openssl.cnf) |
Location of the OpenSSL configuration file. |
|
ReceiveTimeout= |
(20000) ms |
Time in milliseconds before a receive timeout |
|
TCPKeepAlive= |
0 = false (1 = true) |
TCPKeepAliveTCPKeepAlive is a TCP stack option, available at the LunaClient, and at the SafeNet Luna Network HSM appliance. For SafeNet purposes, it is controlled via an entry in the Chrystoki.conf /crystoki.ini file on the LunaClient, and in an equivalent file on SafeNet Luna Network HSM. For SafeNet Luna HSM 6.1 and newer, a fresh client software installation includes an entry "TCPKeepAlive=1" in the "LunaSA Client" section of the configuration file Chrystoki.conf (Linux/UNIX) or crystoki.ini (Windows). Config files and certificates are normally preserved through an uninstall, unless you explicitly delete them. As such, if you update (install) LunaClient software where you previously had an older LunaClient that did not have a TCPKeepAlive entry, one is added and set to "1" (enabled), by default. In the case of update, if TCPKeepAlive is already defined in the configuration file, then your existing setting (enabled or disabled) is preserved. On the SafeNet Luna Network HSM appliance, where you do not have direct access to the file system, the TCPKeepAlive= setting is controlled by the LunaSH command 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 in one direction. |
|
NetClient= |
0 = false (1 = true) |
If true, library will search for network slots |
|
ServerCAFile= |
(<luna_client_dir>\cert\server\CAFile.pem) |
Location, on the client, of the server certificate file (set by vtl or LunaCM command clientconfig deploy). |
|
ClientCertFile= |
(<luna_client_dir>\cert\client\ClientNameCert.pem) |
Location of the Client certificate file that is uploaded to SafeNet Luna Network HSM for NTLS (set by vtl or LunaCM command clientconfig deploy). |
|
ClientPrivKeyFile= |
(<luna_client_dir>\cert\client\ClientNameKey.pem) |
Location of the Client private key file (set by vtl or LunaCM command clientconfig deploy). |
|
ServerName00=192.20.17.200 ServerPort00=1792 ServerName01= ServerPort01= |
|
Entries embedded by vtl utility, when you run the command vtl addserver or the LunaCM command clientconfig deploy. Identifies the NTLS-linked SafeNet Luna Network HSM servers, and determines the order in which they are polled to create a slot list. |
|
NOTE: The Presentation section is not created automatically. To change any of the following values, you must first create this section in the configuration file. [Presentation] |
||
|
ShowUserSlots=<slot>(<serialnumber>) |
Comma-delimited list of <slotnumber>(<serialnumber>), like ShowUserSlots=1(351970018022),2(351970018021),3(351970018020),.... |
Sets the starting slot for the identified partition. If one partition slot on an HSM is specified, then any that are not listed from that HSM are not displayed. |
|
ShowAdminTokens= |
0/(1) |
Admin partitions of local SafeNet Luna PCIe HSMs are not visible/(visible) in a slot listing |
|
ShowEmptySlots= |
(0)/1 |
When the number of partitions on an HSM is not at the limit, unused slots are shown/(not shown). |
|
OneBaseSlotId= |
(0)/1 |
Causes basic slot list to start at slot number 1 instead of (0). |
|
|
||
|
HAOnly= |
(0)/1 |
When set to 1, shows only the HA virtual slot to the client, and hides the physical partitions/slots that are members of the virtual slot. Setting HAOnly helps prevent synchronization problems among member partitions, by forcing all client actions to be directed against the virtual slot, and dealing with synch transparently. HAOnly also prevents the shifting of slot numbers in the slot list that could occur if a visible physical partition were to drop out, which could disrupt an application that identifies its client partitions by slot numbers. |
|
reconnAtt= |
(10) |
Specifies how many reconnection attempts will be made, when a member drops from the group. A value of "-1" is infinite retries. |
|
AutoReconnectInterval= |
(60) s |
Specifies the interval (in seconds) at which the library will attempt to reconnect with a missing member, until "reconnAtt" is reached, and attempts cease. The default value of 60 seconds is the lowest that is accepted. |
|
|
||
|
ToolsDir= |
(<luna_client_dir>\) |
The location of the LunaClient tools. |
| LegacyMemoryReportingMode= | (0)/1 |
Controls the manner in which the HSM reports the available RAM space. Possible values include: >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.
|
|
RSAKeyGenMechRemap= |
(0)/1 |
Controls what happens on newer firmware, when calls are made to specific older mechanisms that are now discouraged due to weakness. When this item is set to 0, no re-mapping is performed. >PKCS Key Gen -> 186-3 Prime key gen >X9.31 Key Gen -> 186-3 Aux Prime key gen (see Mechanism Remap for FIPS Compliance ) |
| RSAPre1863KeyGen MechRemap= |
(0)/1 |
Controls what happens on older firmware, when specific newer mechanisms are called, that are not supported on the older firmware. When the value is set to 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 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 getting a new, secure mechanism, when really you are getting an outdated, insecure mechanism. |
|
ProtectedAuthenticationPathFlagStatus= |
(0)/1/2 |
This flag specifies which role to check for challenge request status. Possible values include: >0 (default): no challenge request >1: check for Crypto Officer challenge request >2: check for Crypto User challenge request Edited using the configurator tool. |
|
CopyRSAPublicValuesFromPrivateTemplate |
0/(1) |
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. Possible values include: >0 : if no public exponent is provided in the public template, then an error is returned (expected behavior). >1(default): if no public exponent is provided in the public template, then the private exponent is copied from the private template to populate the public template
For PKCS#11 compliance, this should be set to "0". |
|
|
||
|
ClientTokenLib= (for 64-bit Windows systems) |
For soft token: ><luna_client_dir>\softtoken.dll For hard token: >C:\Windows\System32\etoken.dll |
Specifies the location of the token library on 64-bit Windows systems. This value must be correct in order to use a client token. For 32-bit systems, see the ClientTokenLib32 entry below. By default, ClientTokenLib 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. The location provided here is the most common location used. |
|
ClientTokenLib32= (for 32-bit Windows systems) |
For soft token: ><luna_client_dir>\win32\softtoken.dll For hard token: >C:\Windows\SysWOW64\etoken.dll |
Specifies the location of the token library on 32-bit Windows systems. This entry appears on Windows only. For 64-bit systems, see the ClientTokenLib entry above. 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. The location provided here is the most common location used. |
