ab_gp_km114_client.h File Reference

A/B-side Subset-114 KMC message decoder - step 2 of Platform_Protocol_KM114's "Consumption design" (see that product's own CLAUDE.md). Takes the raw bytes ab_gp_km114_relay.c reassembled from Gateway and does the actual decode/verify/decrypt this entity's own predefined key makes possible - Gateway never sees any of this, only opaque bytes. More...

#include <stddef.h>
#include <stdint.h>
#include "../../common/site_config.h"
#include "ab_gp_channel.h"

Include dependency graph for ab_gp_km114_client.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
void	ab_gp_km114_client_on_message (const uint8_t *bytes, size_t len, const char *role_tag, rte_example_site_t site, ab_gp_channel_handle_t handle)
	Processes one complete, reassembled Subset-114 message.
int	ab_gp_km114_client_on_peer_digest (const uint8_t *payload, size_t size, const char *role_tag, rte_example_site_t site)
	Consumes a PEER_MSG_KIND_KM114_DIGEST frame from the A/B sibling (called from pre_execute.c's own peer-frame dispatch) and cross-checks it against this side's own most recently installed KMAC for the same serial number, in whichever order the two sides' installs and this frame arrive. Logs MATCH/MISMATCH (snum only, never the key); does nothing if size is too short.

Detailed Description

A/B-side Subset-114 KMC message decoder - step 2 of Platform_Protocol_KM114's "Consumption design" (see that product's own CLAUDE.md). Takes the raw bytes ab_gp_km114_relay.c reassembled from Gateway and does the actual decode/verify/decrypt this entity's own predefined key makes possible - Gateway never sees any of this, only opaque bytes.

Stateful across calls within one process (KTRANS1/KTRANS2 from a prior INSTALL_TRANSPORT_KEY are needed to process a later ADD_AUTHENTICATION_KEY) but deliberately NOT persisted across a restart - see this file's own "Known limitation" note.

Definition in file ab_gp_km114_client.h.

Function Documentation

ab_gp_km114_client_on_message()

void ab_gp_km114_client_on_message	(	const uint8_t *	bytes,
		size_t	len,
		const char *	role_tag,
		rte_example_site_t	site,
		ab_gp_channel_handle_t	handle )

Processes one complete, reassembled Subset-114 message.

Dispatches by the message's own header type:

• INSTALL_TRANSPORT_KEY: MAC-verified with the library's built-in predefined key (KM114_PREDEFINED_KEY); on success, KTRANS1/KTRANS2 are held in-process for later calls.
• ADD_AUTHENTICATION_KEY: MAC-verified with the held KTRANS1 (dropped if none is held yet - e.g. arrived before this process's own INSTALL_TRANSPORT_KEY, or after a restart); on success, the K-STRUCT's enc_kmac is decrypted with the held KTRANS2 (km114_decrypt_kmac()) and, if RTE_KM114_KMAC_OUT_FILE is set, written there as 48 lowercase hex characters (Platform_Protocol_SafeComm's own keys.kmac_file convention).
• Any other message type: logged (type + result where applicable), not otherwise acted on - this workspace has no RBC-side use yet for REPLACE_ALL_KEYS, DELETE_ALL_KEYS, DELETE_KEY or RESPONSE_NOTIF beyond knowing they arrived.

The plaintext key is NEVER written to a log line - only its length/serial number/outcome.

On a successful ADD_AUTHENTICATION_KEY, the decoded KMAC is also cross-checked against the A/B sibling's own independently decoded result (PEER_MSG_KIND_KM114_DIGEST, sent here and consumed via ab_gp_km114_client_on_peer_digest()) - step 3 of the consumption design, a free correctness check, not a new vital-fault path: a mismatch is logged (never the key itself), not rebooted on.

Parameters

bytes	The full reassembled message.
len	Its length.
role_tag	This process's own role tag ("A"/"B"), for log lines.
site	This process's own site, for log lines.
handle	This channel's own handle, to send the A/B cross-check frame. May be NULL (the cross-check is then skipped, e.g. from a unit test with no live channel).

Global functions

Definition at line 50 of file ab_gp_km114_client.c.

ab_gp_km114_client_on_peer_digest()

int ab_gp_km114_client_on_peer_digest	(	const uint8_t *	payload,
		size_t	size,
		const char *	role_tag,
		rte_example_site_t	site )

Consumes a PEER_MSG_KIND_KM114_DIGEST frame from the A/B sibling (called from pre_execute.c's own peer-frame dispatch) and cross-checks it against this side's own most recently installed KMAC for the same serial number, in whichever order the two sides' installs and this frame arrive. Logs MATCH/MISMATCH (snum only, never the key); does nothing if size is too short.

Parameters

payload	4-byte snum followed by the 24-byte plaintext KMAC.
size	Length of payload.
role_tag	This process's own role tag, for log lines.
site	This process's own site, for log lines.

Returns

1 if this side's own KMAC for the same snum was already known and matched, -1 if it was known and differed, 0 if payload was malformed or this side has no own KMAC for that snum yet (the comparison then happens later, from install_kmac(), once this side installs its own).

Definition at line 82 of file ab_gp_km114_client.c.