Operation in HA Mode

To operate ProtectToolkit-C in HA Mode, the Cryptoki Library keeps track of the commands sent to a session. In case of session failure, ProtectToolkit-C will re-establish a new session by replaying these commands.

ProtectToolkit-C provides the following functions in HA mode:

>Detects that a session has terminated because of HSM failure and automatically establishes a new session on a functioning HSM

>After an HSM failure is detected, periodically attempts to bring the affected HSM back online

>Restarts an object search at the point of failure

>Restarts an Encrypt, Decrypt, Sign, Verify, SignRecover, VerifyRecover and Digest operation and replays the Update operations (up to a certain data length limit)

>Creates a log entry to note significant events

>Recovers session objects created by:

•C_DeriveKey

•C_UnwrapKey

•C_GenerateKey *

•C_GenerateKeyPair *

NOTE Randomly-generated keys cannot be recovered if they are lost after they have been used in a cryptographic operation (otherwise, inconsistent results may be generated).

You must configure the Cryptoki library to operate ProtectToolkit-C in HA mode by editing the values of the ET_PTKC_GENERAL_LIBRARY_MODE, ET_PTKC_HA_RECOVER_DELAY, and ET_PTKC_HA_RECOVER_WAIT environment variables. For more information about editing the values of these environment variables, refer to ProtectToolkit-C Configuration Items.

To configure a basic HA system

To configure a basic HA system across two ProtectServer Network HSMs with IP addresses 192.168.1.100 and 192.168.1.101, where the participating tokens are labeled "TokName", set these configuration items (see Configuration Items):

ET_PTKC_WLD_SLOT_0=TokName
ET_PTKC_GENERAL_LIBRARY_MODE=HA
ET_PTKC_HA_RECOVER_DELAY=120
ET_PTKC_HA_RECOVER_WAIT=YES

HA Mode Logging

When the library is operating in HA mode, it will generate log messages on certain events. The ET_PTKC_HA_LOG_FILE and ET_PTKC_HA_LOG_NAME configuration items can be used to configure HA mode logging. For more information about editing these configuration items, refer to Work Load Distribution and High Availability Configuration Items.

The HA feature will generate the following log messages.

Message	Type	Meaning
Session potentially not recoverable: <desc>	Warning	Application has performed an operation that makes the session unrecoverable. The <desc> field will describe the type of operation. Only one message of this type is generated per C_Initialize/C_Finalize session.
HSM Failure detected hsmIdx=<>, hsmSlotId=<>	Error	A session has failed due to an HSM failure and the HA has attempted a session recovery. The hsmIdx is the zero-based index of the failing HSM, as specified by the ET_HSM_NETCLIENT_SERVERLIST or in the order the ProtectServer Network HSMs are detected. This is the same order reported by hsmstate utility.
Found HSM Dead:HSM Failed	Error	This message is generated only when ET_PTKC_HA_RECOVER_DELAY and ET_PTKC_HA_RECOVER_WAIT are enabled. For more information about these configuration items, refer to Work Load Distribution and High Availability Configuration Items. It indicates that the library has seen an HSM fail and is holding off all application threads while it attempts to recover the lost HSM.

Message

Type

Meaning

Session potentially not recoverable: <desc>

Warning

Application has performed an operation that makes the session unrecoverable. The <desc> field will describe the type of operation. Only one message of this type is generated per C_Initialize/C_Finalize session.

HSM Failure detected hsmIdx=<>, hsmSlotId=<>

Error

A session has failed due to an HSM failure and the HA has attempted a session recovery. The hsmIdx is the zero-based index of the failing HSM, as specified by the ET_HSM_NETCLIENT_SERVERLIST or in the order the ProtectServer Network HSMs are detected. This is the same order reported by hsmstate utility.

Found HSM Dead:HSM  Failed

Error

This message is generated only when ET_PTKC_HA_RECOVER_DELAY and ET_PTKC_HA_RECOVER_WAIT are enabled. For more information about these configuration items, refer to Work Load Distribution and High Availability Configuration Items.

It indicates that the library has seen an HSM fail and is holding off all application threads while it attempts to recover the lost HSM.