The site's takeover key and the token codec for the dispatcher takeover confirmation (ADR-040 step 4b). More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "rte/redundancy/site_role/rte_site_role.h"

Include dependency graph for ab_gp_takeover_key.h:

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

Go to the source code of this file.

Macros
#define	AB_GP_TAKEOVER_KEY_FILE_ENV "RTE_TAKEOVER_KEY_FILE"
#define	AB_GP_TAKEOVER_TOKEN_PREFIX "token="

Functions
bool	ab_gp_takeover_key_load_file (const char *path)
	Loads the key file (one key, 48 hex characters) into this process's key slot.
bool	ab_gp_takeover_key_loaded (void)
bool	ab_gp_takeover_verify_mac (void user, const uint8_t msg, size_t msg_len, const uint8_t mac[RTE_SITE_ROLE_TOKEN_MAC_LEN])
	rte_site_role verify_mac callback: true only when a key is loaded and the Subset-037 MAC over msg matches.
bool	ab_gp_takeover_token_from_payload (const char *payload, uint8_t out[RTE_SITE_ROLE_TOKEN_LEN])
	Decodes a util payload token=<48 hex> into a token.
bool	ab_gp_takeover_token_build (uint8_t site_id, uint8_t channel_id, uint32_t challenge, uint32_t seq, uint8_t out[RTE_SITE_ROLE_TOKEN_LEN])
	Builds a token for one channel: the message (version, site id, channel id, challenge, issuer sequence) and its Subset-037 MAC with the loaded key.
bool	ab_gp_takeover_token_to_payload (const uint8_t token[RTE_SITE_ROLE_TOKEN_LEN], char *out, size_t out_size)
	Encodes a token as the util payload token=<48 hex> (NUL-terminated).

Detailed Description

The site's takeover key and the token codec for the dispatcher takeover confirmation (ADR-040 step 4b).

Platform_RTE's rte_site_role checks a takeover token (RTE_SITE_ROLE_TOKEN_LEN bytes) against this channel's challenge; the MAC itself is checked here, with the Subset-037 MAC of Platform_Protocol_SafeComm (RTE links no crypto). The key comes from the file named by RTE_TAKEOVER_KEY_FILE: one line of 48 hex characters (24 bytes, the 3DES key used directly as the MAC key), # comments allowed - the same encoding as SafeComm's kmac_file. The issuer (the status Gateway, on a Maintenance Web request) MACs with the same file.

On the util link (RBC_UTIL_TOPIC_TAKEOVER_CONFIRM) the token travels as the ASCII payload token=<48 hex>.

Definition in file ab_gp_takeover_key.h.

Macro Definition Documentation

◆ AB_GP_TAKEOVER_KEY_FILE_ENV

#define AB_GP_TAKEOVER_KEY_FILE_ENV "RTE_TAKEOVER_KEY_FILE"

Environment variable naming the takeover key file. Unset or empty: the interim unauthenticated path.

Definition at line 27 of file ab_gp_takeover_key.h.

◆ AB_GP_TAKEOVER_TOKEN_PREFIX

#define AB_GP_TAKEOVER_TOKEN_PREFIX "token="

Payload prefix of a token frame on the util link.

Definition at line 30 of file ab_gp_takeover_key.h.

Function Documentation

◆ ab_gp_takeover_key_load_file()

bool ab_gp_takeover_key_load_file ( const char * path )

Loads the key file (one key, 48 hex characters) into this process's key slot.

Returns: true on success; false (slot left empty) when the file cannot be read, holds no key, more than one key or a malformed one.

Definition at line 75 of file ab_gp_takeover_key.c.

◆ ab_gp_takeover_key_loaded()

bool ab_gp_takeover_key_loaded ( void )

Returns: true once a key has been loaded.

Definition at line 116 of file ab_gp_takeover_key.c.

◆ ab_gp_takeover_verify_mac()

bool ab_gp_takeover_verify_mac	(	void *	user,
		const uint8_t *	msg,
		size_t	msg_len,
		const uint8_t	mac[RTE_SITE_ROLE_TOKEN_MAC_LEN] )

rte_site_role verify_mac callback: true only when a key is loaded and the Subset-037 MAC over msg matches.

Definition at line 121 of file ab_gp_takeover_key.c.

◆ ab_gp_takeover_token_from_payload()

bool ab_gp_takeover_token_from_payload	(	const char *	payload,
		uint8_t	out[RTE_SITE_ROLE_TOKEN_LEN] )

Decodes a util payload token=<48 hex> into a token.

Returns: true for exactly that form (case-insensitive hex, nothing after it); false otherwise.

Definition at line 139 of file ab_gp_takeover_key.c.

◆ ab_gp_takeover_token_build()

bool ab_gp_takeover_token_build	(	uint8_t	site_id,
		uint8_t	channel_id,
		uint32_t	challenge,
		uint32_t	seq,
		uint8_t	out[RTE_SITE_ROLE_TOKEN_LEN] )

Builds a token for one channel: the message (version, site id, channel id, challenge, issuer sequence) and its Subset-037 MAC with the loaded key.

Returns: false when no key is loaded or out is NULL.

Definition at line 151 of file ab_gp_takeover_key.c.

◆ ab_gp_takeover_token_to_payload()

bool ab_gp_takeover_token_to_payload	(	const uint8_t	token[RTE_SITE_ROLE_TOKEN_LEN],
		char *	out,
		size_t	out_size )

Encodes a token as the util payload token=<48 hex> (NUL-terminated).

Returns: false when out_size is too small (needs 6 + 48 + 1 bytes) or an argument is NULL.

Definition at line 181 of file ab_gp_takeover_key.c.

Macros

Functions