|
Home > |
Administration Guide > Configuration File Summary
|
|---|
Many aspects of SafeNet HSM configuration and operation are controlled or adjusted by the Chrystoki.conf file (Linux/UNIX) or Crystoki.ini file (Windows).
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 Client folder, installed by the SafeNet 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 such as 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 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 HSM setup, already configured and tweaked to your satisfaction, those settings are preserved when you update to newer SafeNet Client.
Note: For SafeNet Network HSM, shell commands (lunash:>) use on-board default configuration settings. Clients that are sent to the HSM via SafeNet HSM Client, making use of the client library, include the relevant configuration settings from the client-side Chrystoki.conf / Crystoki.ini configuration file.
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 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 HSM client installation, for example<luna_client_dir> on Windows.
| Setting | Range (Default) | Description |
|---|---|---|
|
[Chrystoki2] |
||
| LibNT= | (<luna_client_dir>\cryptoki.dll ) | Path to the Chrystoki2 library |
|
[Luna] |
||
| PEDTimeout1= pedtimeout ped timeout |
( 100000 ) | Specifies the PED timeout time 1 - defines how long 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 ) |
Specifies the PED timeout time 2 - defines how long 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. NOTE: The (default) value of 200000 is necessary to support Small Form-Factor Backup. |
| PEDTimeout3= | (10000) | Specifies the PED timeout time 3 - defines additional time 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 ) | Sets the default timeout interval - defines how long 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 ) | This is such an exception to DefaultTimeout (above). It defines timeout 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. NOTE: The (default) value of 720000 is necessary to support Small Form-Factor Backup. |
| KeypairGenTimeOut= | ( 2700000 ) | The amount of time 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 ) | |
|
[CardReader] |
||
| 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 USB HSM slots reserved so that the library will check for connected devices. Can be set to zero if you have no SafeNet 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. Says Sam in [Discuss-HSM] |
|
[RBS] |
||
| HostName= | Any hostname or IP address ( 0.0.0.0 ) |
|
| HostPort= | Any unassigned port (1792) |
|
| ClientAuthFile= | (<luna_client_dir>\config\clientauth.dat ) | |
| ServerCertFile= | (<luna_client_dir>\cert\server\server.pem ) | |
| ServerPrivKeyFile= | (<luna_client_dir>\cert\server\serverkey.pem ) | |
| ServerSSLConfigFile= | (<luna_client_dir>\openssl.cnf ) | |
| CmdProcessor= | (<luna_client_dir>\rbs_processor2.dll ) | |
| NetServer= | 0 = false (1 = true) |
|
|
[LunaSA Client] |
||
| HtlDir= | (<luna_client_dir>\htl\ ) | Location of HTL-related files - dhparams certificate, htl_client, and the logs directory |
| SSLConfigFile= | (<luna_client_dir>\openssl.cnf ) | Location of the OpenSSL configuration file. |
| ReceiveTimeout= | in milliseconds ( 20000 ) |
Number of milliseconds before a receive timeout |
| TCPKeepAlive= | 0 = false (1 = true) |
TCPKeepAliveTCPKeepAlive is a TCP stack option, available at the LunaClient, and at the SafeNet 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 Network HSM. For SafeNet 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 Network HSM appliance, where you do not have direct access to the file system, the TCPKeepAlive= setting is controlled by the lunash:> ntls TCPKeepAlive set command. 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) |
| ClientCertFile= | (<luna_client_dir>\cert\client\ClientNameCert.pem ) | Location of the Client certificate file that is uploaded to SafeNet Network HSM for NTLS. (set by vtl) |
| ClientPrivKeyFile= | (<luna_client_dir>\cert\client\ClientNameKey.pem ) | Location of the Client private key file. (set by vtl) |
| ServerName00=192.20.17.200
ServerPort00=1792 ServerHtl00=0 ServerName01= ServerPort01= ServerHtl01= |
Entries embedded by VTL utility, when you run "vtl addServer" command. Identifies the NTLS-linked SafeNet Network HSM servers, and determines the order in which they are polled to create a slot list. | |
|
[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 (affects only PPSO partitions). If one PPSO slot on an HSM is specified, then any that are not listed from that HSM are not displayed. |
| ShowAdminTokens= | yes/(no) | Admin partitions of local HSMs are visible/(not 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). |
|
[HAConfiguration] |
||
| 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) seconds | Specifies the interval 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. |
|
[Misc] |
||
| ToolsDir= | (<luna_client_dir>\ ) | |
| PE1746Enabled= | 0 = false (1 = true) |
Specifies the performance target for symmetric operations based on packet sizes. For small packets, turn off this setting. |
| 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. When the value is set to 1, the following re-mapping occurs if the HSM firmware permits: •PKCS Key Gen -> 186-3 Prime key gen •X9.31 Key Gen -> 186-3 Aux Prime key gen |
| 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 this item is set to 0, no re-mapping is performed. 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. |
|
[Secure Trusted Channel] |
||
| ClientIdentitiesDir= | <luna_client_dir>\data\client_identities | Specifies the directory used to store the STC client identity. |
| PartitionIdentitiesDir= | <luna_client_dir>\data\partition_identities |
Specifies the directory used to store the STC partition identities exported using the LunaCM stcconfig partitionid export command. |
| ClientTokenLib= |
For soft token: •<luna_client_dir>\softtoken.dll •<luna_client_dir>\win32\softtoken.dll (32-bit Windows) For hard token: •C:\Windows\System32\etoken.dll (Windows) •/usr/lib/libetoken.so (32-bit Linux/UNIX) •/usr/lib64/libetoken.so (64-bit Linux/UNIX) |
Specifies the location of the token library. This value must be correct in order to use a client token. 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. |
| SoftTokenDir= | <luna_client_dir>\softtoken |
Specifies the location where the STC client soft token (token.db) is stored. Each client soft token is stored in its own numbered subdirectory. Note: In this release there is only one client token, which is stored in the 001 subdirectory. |