Configuration Items

This chapter contains instructions for making configuration changes on ProtectServer client and server systems. The procedure for editing configuration items is different for ProtectServer External 2 HSMs, client machines, and systems hosting ProtectServer PCIe 2 HSMs. Please refer to the section relevant to your system:

>Overview

>Client/PCIe HSM Server Configuration

>ProtectServer External 2 Server Configuration

Configuration options are described here:

>Network Mode Client Configuration Items

>PCI Mode Client Configuration Items

>Network Mode Server Configuration Items

>Software-Only Mode Configuration

>Specifying the Network Server(s)

Overview

During installation, configuration items are created on the host system. Configuration changes are made by editing the values associated with these items. This chapter describes how to make such changes on your system.

Item values can exist at four configuration levels. When a configuration item is queried, item locations are searched in order of level precedence:

1.Temporary: Any changes made at the temporary configuration level override any corresponding entries at the user, system, and default levels.

2.User: Changes made at the user level override any corresponding entries at the system and default levels.

3.System: System changes override default-level entries.

4.Default: If no changes have been made at any other level, the default value for the configuration item is used. Default configuration values cannot be changed.

On Windows operating systems, user and system configuration information is stored in the Registry. On Unix-based systems, configuration files are used. Temporary configuration items are applied using environment variables on both Windows and Unix-based platforms.

Regardless of the platform, a common naming convention for configuration items has been followed. Understanding this naming convention will help you locate and change the appropriate configuration items when required.

Configuration items are hierarchical in structure, with the root node ET. Child nodes of the root represent the class of the item, and are typically product abbreviations, such as PTKC (ProtectToolkit-C) or HSM (Hardware Security Module). Nodes under class represent the component, such as LOGGER or SMS. Finally, nodes under component represent the configuration item, such as FILE, MODE, or NAME. Configuration items therefore take the form:

ET_<class>_<component>_<item>

For a list of configurable items, see:

>PCI Mode Client Configuration Items

>Network Mode Client Configuration Items

>Network Mode Server Configuration Items

Client/PCIe HSM Server Configuration

The procedure for configuring client/PCIe HSM host systems differs between Windows and Linux. Please refer to the relevant section below:

Windows

Temporary

Temporary configuration changes are made using environment variables. Since environment variables are not hierarchical, the hierarchy is implicitly defined by the name of the variable.

In Network mode, to temporarily change the length of time the HSM will wait before timing out a connection attempt

In a command prompt, enter set ET_HSM_NETCLIENT_CONNECT_TIMEOUT_SECS=<time_in_seconds>

User

User configuration changes are made in the registry tree starting from HKEY_CURRENT_USER\SOFTWARE\SafeNet.

In Network mode, to change the length of time the HSM will wait before timing out a connection attempt

1.Open regedit to HKEY_CURRENT_USER\SOFTWARE\SafeNet.

2.Add a new key entitled HSM and open it.

3.Add a new key entitled NETCLIENT and open it.

4.Add a new string named ET_HSM_NETCLIENT_CONNECT_TIMEOUT_SECS.

5.Set the value data to the desired time in seconds.

System

System configuration changes are made in the registry tree starting from HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet.

The name of the ProtectToolkit-C file where the logger library writes log information (ctlog.log) is stored in the Windows registry as a string value for the entry:
ET_PTKC_LOGGER_FILE

This is located in the key:
HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet\PTKC\LOGGER

Unix

Temporary

Temporary configuration changes are made using environment variables. Since environment variables are not hierarchical in nature, the hierarchy is implicitly defined by the name of the variable.

User

User Configuration is a set of files located in the $HOME/.safenet directory.

System

System Configuration is a set of files located in the /etc/default directory.

The User and System Configuration files are of the form: et_<class>. Entries in the file are of the form: ET_<class>_<component>_<item>=<value>.

The name of the ProtectToolkit-C file where the logger library writes log information (ctlog.log) is stored in the /etc/default/et_ptkc file as the entry:

ET_PTKC_LOGGER_FILE=/ctlog.log

ProtectServer External 2 Server Configuration

Server configuration settings on the ProtectServer External 2 are edited by transferring a new configuration file to the appliance, and applying it using PSESH.

To change the ProtectServer External 2 server configuration

1.Create a text file on your client machine that lists each configuration item and its desired value. For a list of editable configuration items and their valid values, see Network Mode Server Configuration Items.

For example:

ET_HSM_NETSERVER_OLD_WORKER_COUNT=5
ET_HSM_NETSERVER_V2_WORKER_COUNT=12
ET_HSM_NETSERVER_READ_TIMEOUT_SECS=40
ET_HSM_NETSERVER_WRITE_TIMEOUT_SECS=40
ET_HSM_NETSERVER_CONN_TIMEOUT_COUNT=5
ET_HSM_NETSERVER_FRAG_SIZE=5000
ET_HSM_NETSERVER_ALLOW_RESET=OnHalt
ET_HSM_NETSERVER_PORT=12396
ET_HSM_NETSERVER_LOG_CHANNEL=0
ET_HSM_NETSERVER_LOG_NAME=etnetserver
ET_HSM_NETSERVER_LOG_LEVEL=0

2.Transfer the configuration file (et_hsm.txt in the example below) to the admin or pseoperator user on the appliance using pscp (Windows) or scp (Linux/UNIX):

Windows

pscp <filename> admin@<server_host/IP>:

pscp  et_hsm.txt admin@192.168.0.123: 
admin@192.168.0.123's password: ********  
et_hsm.txt                | 0 kB |   0.4 kB/s | ETA: 00:00:00 | 100%
Linux/UNIX

scp <filename> admin@<server_host/IP>:

scp et_hsm.txt admin@192.168.0.123: 
admin@192.168.0.123's password: ********  
et_hsm.txt                | 0 kB |   0.4 kB/s | ETA: 00:00:00 | 100%

3.Login to PSESH as admin or pseoperator.

4.If desired, check to ensure that the configuration file was transferred to the appliance.

psesh:>files show

psesh:>files show

SCP Folder Content
------------------

total 0.4K
0.4K et_hsm.txt

Command Result : 0 (Success)

5.Set the etnetserver configuration file. See sysconf etnetcfg for syntax.

psesh:>sysconf etnetcfg set <filename>

psesh:>sysconf etnetcfg set et_hsm.txt

WARNING !!  This command will modify the settings of the appliance.
            It could affect client connections, and result in an unusable system.
If you are sure that you wish to proceed, then type 'proceed', otherwise type 'quit'

> proceed
Proceeding...
The config file has been set. To apply the changes, please restart etnetserver


Command Result : 0 (Success)

6.Restart the etnetserver service.

psesh:>service restart etnetserver

7.View the new configuration to confirm the changes.

psesh:>sysconf etnetcfg show

psesh:>sysconf etnetcfg show


etnetserver is running

Current etnetserver configuration

ET_HSM_NETSERVER_OLD_WORKER_COUNT=5
ET_HSM_NETSERVER_V2_WORKER_COUNT=12
ET_HSM_NETSERVER_READ_TIMEOUT_SECS=40
ET_HSM_NETSERVER_WRITE_TIMEOUT_SECS=40
ET_HSM_NETSERVER_CONN_TIMEOUT_COUNT=5
ET_HSM_NETSERVER_FRAG_SIZE=5000
ET_HSM_NETSERVER_ALLOW_RESET=OnHalt
ET_HSM_NETSERVER_PORT=12396
ET_HSM_NETSERVER_LOG_CHANNEL=0
ET_HSM_NETSERVER_LOG_NAME=etnetserver
ET_HSM_NETSERVER_LOG_LEVEL=0

Command Result : 0 (Success)