ab_gp_km114_client.c

Go to the documentation of this file.

#include "ab_gp_km114_client.h"
#include "ab_gp_saf_train.h"
 
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
#include "rte/oal/log/rte_log.h"
#include "km114/km114.h"



/* Known limitation (documented, not accidental): held in-process only, not persisted across a
 * restart. If ADD_AUTHENTICATION_KEY is relayed in a separate KMC drop after this process
 * restarted since its own INSTALL_TRANSPORT_KEY, it is dropped (logged) rather than silently
 * misapplied - the off-line KMC operator re-sends INSTALL_TRANSPORT_KEY in that case, the same
 * operational recovery Subset-114 itself assumes for a lost/corrupted transfer. */
static bool    s_have_ktrans = false;
static uint8_t s_ktrans1[KM114_MAC_KEY_LEN];
static uint8_t s_ktrans2[KM114_MAC_KEY_LEN];
 
/* A/B cross-check (step 3 of the consumption design): each side's own most recently installed KMAC, and whatever
 * the sibling last sent, kept independently since the two installs and the sibling's frame can arrive in any order -
 * see ab_gp_km114_client_on_peer_digest()'s own doc. Never logged, only compared. */
static bool     s_have_own    = false;
static uint32_t s_own_snum    = 0U;
static uint8_t  s_own_kmac[KM114_MAC_KEY_LEN];
static bool     s_have_peer   = false;
static uint32_t s_peer_snum   = 0U;
static uint8_t  s_peer_kmac[KM114_MAC_KEY_LEN];

static void handle_install_transport_key(const uint8_t *bytes, size_t len, const char *role_tag,
                                          rte_example_site_t site);
static void handle_add_authentication_key(const uint8_t *bytes, size_t len, const char *role_tag,
                                          rte_example_site_t site, ab_gp_channel_handle_t handle);
static void install_kmac(const uint8_t kmac[KM114_MAC_KEY_LEN], uint32_t snum, const char *role_tag,
                         rte_example_site_t site, ab_gp_channel_handle_t handle);
static int km114_cross_check(const char *role_tag, rte_example_site_t site);

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)
{
    km114_header_t hdr;
 
    if ((bytes == NULL) || (km114_decode_header(bytes, len, &hdr) != KM114_STATUS_OK))
    {
        rte_log_write_event(RTE_LOG_LEVEL_WARNING, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                              "malformed message header", NULL);
        return;
    }
 
    switch (hdr.message_type)
    {
        case KM114_MSG_INSTALL_TRANSPORT_KEY:
            handle_install_transport_key(bytes, len, role_tag, site);
            break;
        case KM114_MSG_ADD_AUTHENTICATION_KEY:
            handle_add_authentication_key(bytes, len, role_tag, site, handle);
            break;
        default:
        {
            char info[32];
 
            (void)snprintf(info, sizeof(info), "type=0x%02X", (unsigned int)hdr.message_type);
            rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                                  "message received, not acted on", info);
            break;
        }
    }
}
 
int ab_gp_km114_client_on_peer_digest(const uint8_t *payload, size_t size, const char *role_tag,
                                       rte_example_site_t site)
{
    if ((payload == NULL) || (size < (4U + (size_t)KM114_MAC_KEY_LEN)))
    {
        return 0;
    }
    s_peer_snum = ((uint32_t)payload[0] << 24) | ((uint32_t)payload[1] << 16) |
                  ((uint32_t)payload[2] << 8) | (uint32_t)payload[3];
    (void)memcpy(s_peer_kmac, &payload[4], (size_t)KM114_MAC_KEY_LEN);
    s_have_peer = true;
    return km114_cross_check(role_tag, site);
}
 
/****Local functions ****/
 
static void handle_install_transport_key(const uint8_t *bytes, size_t len, const char *role_tag,
                                          rte_example_site_t site)
{
    km114_header_t                 hdr;
    km114_install_transport_key_t body;
 
    if (km114_parse_install_transport_key(bytes, len, &hdr, &body) != KM114_STATUS_OK)
    {
        rte_log_write_event(RTE_LOG_LEVEL_WARNING, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                              "INSTALL_TRANSPORT_KEY MAC/parse failed", NULL);
        return;
    }
    (void)memcpy(s_ktrans1, body.ktrans1, KM114_MAC_KEY_LEN);
    (void)memcpy(s_ktrans2, body.ktrans2, KM114_MAC_KEY_LEN);
    s_have_ktrans = true;
 
    {
        char info[32];
 
        (void)snprintf(info, sizeof(info), "snum=%u", (unsigned int)body.new_kt_snum);
        rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                              "KTRANS1/KTRANS2 installed", info);
    }
}

static void install_train_link_keys(const km114_kstruct_t *ks, const uint8_t kmac[KM114_MAC_KEY_LEN],
                                    const char *role_tag, rte_example_site_t site)
{
    uint16_t i;
    uint16_t installed = 0U;
    char info[48];
 
    for (i = 0U; (i < ks->peer_num) && (i < (uint16_t)KM114_MAX_PEERS); i++)
    {
        if (ab_gp_saf_keys_install(ks->peers[i].id & 0xFFFFFFU, kmac))
        {
            installed++;
        }
    }
    (void)snprintf(info, sizeof(info), "snum=%u peers=%u installed=%u", (unsigned int)ks->snum,
                   (unsigned int)ks->peer_num, (unsigned int)installed);
    rte_log_write_event((installed == ks->peer_num) ? RTE_LOG_LEVEL_INFO : RTE_LOG_LEVEL_WARNING,
                          site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                          "KMAC installed for the train-link safe connection", info);
}
 
static void handle_add_authentication_key(const uint8_t *bytes, size_t len, const char *role_tag,
                                          rte_example_site_t site, ab_gp_channel_handle_t handle)
{
    km114_header_t  hdr;
    km114_kstruct_t ks;
    uint8_t         kmac[KM114_MAC_KEY_LEN];
 
    if (!s_have_ktrans)
    {
        rte_log_write_event(RTE_LOG_LEVEL_WARNING, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                              "ADD_AUTHENTICATION_KEY dropped - no KTRANS held", NULL);
        return;
    }
    if (km114_parse_add_authentication_key(bytes, len, s_ktrans1, &hdr, &ks) != KM114_STATUS_OK)
    {
        rte_log_write_event(RTE_LOG_LEVEL_WARNING, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                              "ADD_AUTHENTICATION_KEY MAC/parse failed", NULL);
        return;
    }
    km114_decrypt_kmac(s_ktrans2, ks.enc_kmac, kmac);
    install_kmac(kmac, ks.snum, role_tag, site, handle);
    install_train_link_keys(&ks, kmac, role_tag, site);
    (void)memset(kmac, 0, sizeof(kmac));
}

static void send_km114_digest(ab_gp_channel_handle_t handle, uint32_t snum, const uint8_t kmac[KM114_MAC_KEY_LEN])
{
    uint8_t frame[PEER_WIRE_FRAME_SIZE] = { 0 };
 
    if (handle == NULL)
    {
        return; /* no live channel (e.g. a unit test calling install_kmac() directly) - nothing to cross-check */
    }
    frame[0] = PEER_MSG_KIND_KM114_DIGEST;
    frame[1] = (uint8_t)(snum >> 24);
    frame[2] = (uint8_t)(snum >> 16);
    frame[3] = (uint8_t)(snum >> 8);
    frame[4] = (uint8_t)snum;
    (void)memcpy(&frame[5], kmac, (size_t)KM114_MAC_KEY_LEN);
    (void)ab_gp_channel_send_peer(handle, frame, sizeof(frame));
}

static int km114_cross_check(const char *role_tag, rte_example_site_t site)
{
    char info[16];
    int  result;
 
    if (!s_have_own || !s_have_peer || (s_own_snum != s_peer_snum))
    {
        return 0;
    }
    (void)snprintf(info, sizeof(info), "snum=%u", (unsigned int)s_own_snum);
    if (memcmp(s_own_kmac, s_peer_kmac, (size_t)KM114_MAC_KEY_LEN) == 0)
    {
        rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                              "KMAC cross-check with A/B sibling: MATCH", info);
        result = 1;
    }
    else
    {
        rte_log_write_event(RTE_LOG_LEVEL_WARNING, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                              "KMAC cross-check with A/B sibling: MISMATCH", info);
        result = -1;
    }
    return result;
}
 
static void install_kmac(const uint8_t kmac[KM114_MAC_KEY_LEN], uint32_t snum, const char *role_tag,
                         rte_example_site_t site, ab_gp_channel_handle_t handle)
{
    const char *out_path = getenv("RTE_KM114_KMAC_OUT_FILE");
    char        info[48];
 
    /* Cross-check regardless of whether this side even installs the key to a file below - it is about whether A and
     * B independently decoded the SAME key, not about what either side then does with it. */
    s_own_snum = snum;
    (void)memcpy(s_own_kmac, kmac, (size_t)KM114_MAC_KEY_LEN);
    s_have_own = true;
    send_km114_digest(handle, snum, kmac);
    km114_cross_check(role_tag, site);
 
    (void)snprintf(info, sizeof(info), "snum=%u", (unsigned int)snum);
 
    if ((out_path == NULL) || (out_path[0] == '\0'))
    {
        /* Not configured - the decoded key is discarded. Logged at INFO, not WARNING: this is
         * a valid, common state (a process not participating in key installation, e.g. a test
         * run) not a fault. */
        rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                              "KMAC decoded, RTE_KM114_KMAC_OUT_FILE unset - not installed", info);
        return;
    }
 
    {
        FILE   *fp = fopen(out_path, "w");
        size_t  i;
 
        if (fp == NULL)
        {
            rte_log_write_event(RTE_LOG_LEVEL_ERROR, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                                  "KMAC decoded, keys.kmac_file open failed", info);
            return;
        }
        for (i = 0U; i < (size_t)KM114_MAC_KEY_LEN; i++)
        {
            (void)fprintf(fp, "%02x", (unsigned int)kmac[i]);
        }
        (void)fprintf(fp, "\n");
        (void)fclose(fp);
    }
    /* Never log the key itself - only that installation happened and its serial number. */
    rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), 0U, role_tag, "-", "KM114_CLIENT",
                          "KMAC installed", info);
}