Network Communication and Power Failure Error Handling

Posser failure as well as network issues can occur in real environment. To protect failures or duplicate keys injected there was introduced failure protection described her

Upload keys failure management

When the user clicks the Upload option to send/upload keys to the terminal, a few failures are possible.

The network connection can be a problem especially if Wi-Fi used is not stable.

Power to KLD or the Terminal may be lost accidentally. In these cases, there is a chance the KLD sent a key to the terminal, the terminal successfully installed it, but the KLD did not receive the response. In these cases, KLD will have to assume that the terminal received the key(s) and delete them from the local repository to avoid sending the same key to a different terminal. In case of BDK, the DID must be increased. This assumption may delete a Master or IK keys even if the Terminal did not receive the key, but this is the trade-off vs sending the same to multiple terminals in case of these edge cases.

Key State Change Conditions During Upload

DID Increment and IK/Master Key Deletion

Scope: From the moment the user starts an upload until the upload (and any crash recovery) is fully complete.

Two types of key state changes occur after an upload:

Key Type	Description
BDK	DID incremented by 1; key deleted when DID exceeds DID_END
IK	Top key entry deleted from the key list file
Master (MS)	Top key entry deleted from the key list file

Conditions by Send (or Upload) outcome

1. Successful Send (status = 0)

The KRD acknowledged receipt (HTTP 200, confirmed success).

Key Type	Text
BDK	DID incremented by 1 in repo (or key deleted if DID > DID_END)
IK	Top key entry deleted from the IK key list
Master	Top key entry deleted from the MS key list

KeyInfoLog.log: Entry written. Comm Status = SUCCESS.

2. KRD Explicitly Rejected the Key (ERROR_KEYS_DOWNLOAD_FAILED)

The terminal responded with an explicit rejection (HTTP non-200 or status=failed). The key was not loaded by the KRD.

Key Type	Description
BDK	No change. DID is not incremented.
IK	No change. Key entry is not deleted.
Master	No change. Key entry is not deleted.

KeyInfoLog.log: No entry written.

3. Pre-Network Error (ERROR_KLD_INTERNAL)

The send failed before any data left the device (e.g., URL construction failed). The key was never transmitted.

Key Type	Description
BDK	No change. DID is not incremented.
IK	No change. Key entry is not deleted.
Master	No change. Key entry is not deleted.

KeyInfoLog.log: No entry written.

4. Communication Failure — Data May Have Been Sent

Two error codes fall in this category:

ERROR_KLD_SERVER_RESPONSE_EMPTY	KLD completed the PUT; response was NULL. Data was transmitted; KRD state is unknown.
ERROR_KLD_HTTP_PUT_FAILED	Transport failed. Data may or may not have reached the KRD.

Policy: once the payload has been put on the wire and the outcome is uncertain, KLD treats the key as possibly loaded.

Key Type	Description
BDK	DID incremented by 1 in repo (or key deleted if DID > DID_END)
IK	Top key entry deleted from the IK key list
Master	Top key entry deleted from the MS key list

KeyInfoLog.log: Entry written. Comm Status = FAILURE.

5. Power Failure or Hang During Send (WAL Replay on Next Boot)

The device lost power (or hung) while upload was executing. No return code was recorded.

On the next KLD startup, KLD reads the WAL (Write Ahead Log) file and runs recovery.

Key Type	Description
BDK	DID incremented by 1 in repo (or key deleted if DID > DID_END)	WAL stores the pre-send DID. Replay only increments if the current repo DID still equals the pre-send DID — prevents double-increment if power failed after cleanup but before WAL was deleted.
IK	Top key entry deleted from the IK key list	Naturally idempotent — if the file was already deleted, the next key shares the same key_file_name_ and is consumed instead. See Notes.
Master	Top key entry deleted from the MS key list	Same as IK.

KeyInfoLog.log: Entry written. Comm Status = FAILURE. The timestamp used is the original send timestamp stored in the WAL — it reflects when the interrupted send occurred, not when the device rebooted.