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 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 |
| LNHServerKeepAliveTimer## |
Set the keepalive timer (in milliseconds) for connections to the cluster, specified by ## (refer to LNHServer##). Valid Range: 10000-50000 Default: 30000 NOTE This feature requires Luna HSM Client 10.5.2 or newer, and the cluster package (1.0.2) included with Luna Network HSM 7 Appliance Software 7.8.2 or newer. |
| LNHServerLoadBalancingMode## |
Selects the load-balancing mode the client will use to distribute requests among the members of the cluster, specified by ## (refer to LNHServer##). Valid Values: >pick_first (default): Operation requests are sent to the first cluster member where a connection can be successfully made. >round_robin: Connections are made to all active members, and operation requests are distributed to each active member in turn. NOTE This feature requires Luna HSM Client 10.5.2 or newer, and the cluster package (1.0.2) included with Luna Network HSM 7 Appliance Software 7.8.2 or newer. |
| 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. |
| LNHServerClientCert## | The location and filename of the Luna HSM Client certificate used to access this Luna Network HSM 7 cluster. |
| LNHServerClientKey## | The location and filename of the Luna HSM Client private key used to access this Luna Network HSM 7 cluster. |
| LNHServerCAFile## | The location and filename of the Luna Network HSM 7 cluster server certificate. |
| LNHServerCN## | The Common Name for the cluster certificate. |
| LNHStandbyServer## |
Reports the affinity group the client is directing traffic to. See Moving a Member to a Different Affinity Group. NOTE This feature requires Luna HSM Client 10.5.2 or newer, and the cluster package (1.0.2) included with Luna Network HSM 7 Appliance Software 7.8.2 or newer. |
| 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. |
| ProbeTimeout |
By default, if the HA probing thread makes a request to the Luna Network HSM 7 where the internal cryptographic module (HSM card) is locked up, the probing thread can also lock up, and failover does not occur. To deal with that possibility, this setting, with a value greater than 0, initiates a timeout (in seconds). Valid Values: >0 (default): This is the same effect as the ProbeTimeout setting not existing in this configuration file - no timeout is set. >1 - ?: A number of seconds greater than zero. This is a balancing decision, unique to your application situation. If you wish to set a ProbeTimeout, choose a value •large enough to allow your usual crypto processes to complete normally, but •not so large that a failover, from a failed HA-group member to a healthy member, is never triggered before your application concludes that the entire HA group has failed. This feature requires Luna HSM Client 10.7.2 or newer (with the default 0 value for backward compatibility). |
| 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. |
| 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. 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 |
Using older versions of the Luna HSM Client software, this entry allows you to automatically remap calls to certain old, less-secure mechanisms, to new mechanisms that are FIPS-approved. This remapping allows you to operate the HSM securely without having to rewrite your applications. >0 (default): No re-mapping is performed. >1: The following remapping is applied: •Calls for PKCS key generation using CKM_RSA_PKCS_KEY_PAIR_GEN are remapped to CKM_RSA_FIPS_186_3_PRIME_KEY_PAIR_GEN, which uses 186-3 Prime key generation. •Calls for X9.31 key generation using CKM_RSA_X9_31_KEY_PAIR_GEN are remapped to CKM_RSA_FIPS_186_3_AUX_PRIME_KEY_PAIR_GEN, which uses 186-3 Aux Prime key generation NOTE Using Luna HSM Client 10.1.0 or newer, remapping is automatic and this configuration entry is ignored. For remapping on HSMs where FIPS mode is set on individual partitions, Luna HSM Client 10.4.0 or newer is required; see Applying the Mechanism Remapping for details. |
| 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) (Windows) |
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
>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>; NOTE PartitionData00 is deprecated and included in the bundle to support legacy use cases. This may be removed in a future update. 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 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. NOTE Using Luna Cloud HSM 10.7.2 or higher, users are no longer required to run setenv to configure the client to connect to the Cloud HSM Service. However, setenv may still be used to configure the client for hybrid use cases or integrations where setting the ChrystokiConfigurationPath is required. |
| 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=***********
