ProtectToolkit-C Configuration Items

This chapter lists the available ProtectToolkit-C configuration items and, where applicable, their default values and valid range of values.

NOTE   Thales recommends leaving configuration items at the their default value or setting them to a valid value specified in the following table. If the value of a configuration item must be changed and no valid values are given, contact Thales Customer Support for assistance.

For more information about using configuration items see Configuration Items.

General Configuration Items

The configuration items in the table below are used to configure ProtectToolkit-C more generally.

Configuration Item Meaning 
ET_PTKC_GENERAL_LIBRARY_MODE

The Cryptoki library operating mode.

Valid values:

>NORMAL - Standard PKCS #11 mode.

>WLD - Work Load Distribution mode.

>HA - High Availability mode.

Default=NORMAL

Work Load Distribution and High Availability Configuration Items

The configuration items in the table below are used to configure ProtectToolkit-C for Work Load Distribution (WLD) and High Availability (HA). For more information about these modes, refer to Work Load Distribution Model (WLD) and High Availability (HA).

Configuration Item Meaning 
ET_PTKC_HA_LOG_FILE

The name of the ProtectToolkit-C file where the Cryptoki library generates log messages while operating in HA mode.

>Windows default= c:\ptk_halog.log

>Linux default=/ptk_halog.log

 
ET_PTKC_HA_LOG_NAME

The name of the application.

Default=ptk_cryptoki

 
ET_PTKC_HA_RECOVER_DELAY

The number of minutes the system will wait after an HSM failure before attempting reconnection to the failed HSM. If the value is zero, reconnection is not attempted.

Default=0

 
ET_PTKC_HA_RECOVER_WAIT

Whether the system will poll and attempt recovery if an HSM has failed. This configuration item is valid only if HA mode is enabled.

Valid values:

>YES

>NO 

ET_PTKC_WLD_SLOT_n

The configuration parameters of a WLD slot in a WLD system. In the name of this configuration item, n is an integer (in the range 0 to 99) that defines the slot number. Slot numbers allocated within an application must be unique.

The value of this configuration item is specified in the following format:

<WLDTokenLabel>[,[<WLDTokenSerial#>][,<WLDSlotDescription>]]

><WLDTokenLabel>

This variable is mandatory. The PKCS #11 token label for this WLD token identifies the HSM tokens to be used for WLD. The <WLDTokenLabel> should be unique in the complete list of WLD slot configurations.

><WLDTokenSerial#>

This variable is optional. You can assign any PKCS #11 token serial number you wish to this WLD token. The default value is the same as the value of n in the configuration variable name.

><WLDSlotDescription>

This variable is optional. You can assign any PKCS #11 slot description you wish for this WLD Slot. The default value is “WLD Slot:n”, where n is the same as the value of n in the configuration variable name.

Logger Configuration Items

The configuration items in the table below are used to configure the logger library. For more information about the logger library, refer to PKCS#11 Logger Library.

NOTE   Values for the logger configuration items are located in the HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet\PTKC\LOGGER key on Windows and stored in /etc/default/et_ptkc file on Linux.

Configuration Item Meaning 
ET_PTKC_LOGGER_FILE

The name of the ProtectToolkit-C file where the logger library writes log information.

>Windows default=\ctlog.log

>Linux default=~/ctlog.log

 
ET_PTKC_LOGGER_LOGMEM

Whether all numeric data, buffer addresses, and the contents of buffer addresses at the input and output of functions (excluding PIN values) are included in log messages.

Valid values:

>TRUE

>FALSE - the contents of buffer addresses at the input and output of functions are omitted, while numeric data and buffer addresses are retained.

Default=TRUE

 
ET_PTKC_LOGGER_LOGPID

Whether the calling process ID (PID) is included in log messages.

Valid values:

>TRUE

>FALSE

Default=TRUE

 
ET_PTKC_LOGGER_LOGPIN

Whether the PIN values passed to C_Login, that are used to log into tokens, are included in log messages.

Valid values:

>TRUE

>FALSE

Default=FALSE

 
ET_PTKC_LOGGER_LOGTID

Whether the thread ID (TID) is included in log messages.

Valid values:

>TRUE

>FALSE

Default=TRUE

 
ET_PTKC_LOGGER_LOGTIME

Whether the date and time of each message is included in the log.

Valid values:

>TRUE

>FALSE

Default=TRUE

 
ET_PTKC_LOGGER_PKCS11LIB

Whether the logger is configured for HSM or Software-Only operating mode on Windows.

>Valid values:

•C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C SDK\bin\hsm\cryptoki.dll (for HSM mode)

•C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C SDK\bin\sw\cryptoki.dll (for Software Only mode)

External Key Storage Configuration Items

The configuration items in the table below are used to configure external key storage. For more information about configuring external key storage, refer to External Key Storage.

Configuration Item Meaning 
ET_PTKC_EXTTOKEN_MAXLOADED

The maximum number of objects which will be loaded to the underlying token at one time. If this limit is reached, then the least used object is unloaded from the underlying token.

Default=100

 
ET_PTKC_EXTTOKEN_PATH

The fully qualified directory path that determines where ExtToken library stores its data files. These data files will contain the encrypted key material.

Default=C:\ETExtToken

 
ET_PTKC_EXTTOKEN_PKCS11LIB

The fully qualified file path to Cryptoki library to be used after configuring external key storage for application development or runtime operation.

Located in the HLKM(or HKCU)\SOFTWARE\SafeNet\PTKC\EXTTOKEN registry key on Windows.

Valid values:

>C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C RT\hsm (When configuring external key storage for runtime operation)

>C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C SDK\bin\hsm (When configuring external key storage for application development in HSM operating modes)

>C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C SDK\bin\sw (When configuring external key storage for application development in software-only operating mode)

Secure Messaging Configuration Items

The configuration items in the table below are used to configure the Secure Messaging System (SMS). For more information about the SMS, refer to Secure Messaging.

Configuration Item Meaning 
ET_PTKC_<serial>_SMPR

The Secure Messaging Policy Register (SMPR) security mode flag(s) to enable.

In the name of this configuration item, <serial> is the serial number of the HSM.

Valid values:

>E - Only messages sent to the HSM that contain sensitive data are encrypted (No clear PINs).

>S - Only messages sent to the HSM are signed (Auth Protection).

>R - Only messages received from the HSM are signed (Auth Replies).

 
ET_PTKC_SMS_BLOCKS

The number of blocks that must be encrypted or decrypted by the application before session key rollover is triggered.

Default=4294967296

 
ET_PTKC_SMS_HOURS

The number of hours that must elapse before session key rollover is triggered.

Default=24

 
ET_PTKC_SMS_MODE

Whether ProtectToolkit uses the legacy Anonymous Diffie-Hellman (ADH) mode for secure messaging when the No Clear PINs flag is set.

Valid values:

>ADH

NOTE   PTK firmware versions 5.01.00 and newer support ADH2 only. ADH is included for use with legacy firmware older than 5.01.00. Setting the SMS mode to ADH with newer firmware will return an error message.

Software-Only Mode Configuration Items

The configuration items in the table below are used to configure ProtectToolkit-C for software-only mode. For more information about configuring software-only mode, refer to Software-Only Mode Configuration.

Configuration Item Meaning 
ET_PTKC_SW_DATAPATH

The directory within the local file system where keys and configuration information are stored.

>Windows default=C:\cryptoki

>Linux default=$HOME/.cryptoki/cryptoki