key_vault.c

Go to the documentation of this file.

 
#include "key_vault.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_secure.h"
 
static const char* s_tag = "KEYV";
 
/*
 * Fail-closed stub-crypto gate (issue #180). The SHA-256 below is real
 * (FIPS 180-4), but the surrounding key vault is a software placeholder that
 * holds symmetric keys in a plain secure-SRAM array with no hardware-backed
 * protection -- a stand-in for a real key store. It is only meant for an
 * off-target build or an explicitly-declared insecure dev/eval image. A real
 * production/HIL image (neither flag set) compiles the #else branch, where
 * every entry point hard-errors so the placeholder vault cannot be relied on.
 * scripts/checks/check_stub_crypto_guarded.py enforces the guard.
 */
#if defined(RA8_INSECURE_STUB_CRYPTO) || defined(RA8_OFF_TARGET)

typedef enum : uint16_t {
  k_sha256_msg_bytes   = 32U, 
  k_sha256_words       = 64U, 
  k_sha256_block_bytes = 64U, 
} sha256_dim_t;

typedef enum : uint8_t {
  k_sha256_pad_pos        = 32U,   
  k_sha256_pad_marker     = 0x80U, 
  k_sha256_pad_zero_start = 33U,   
  k_sha256_len_b0         = 56U,   
  k_sha256_len_b1         = 57U,   
  k_sha256_len_b2         = 58U,   
  k_sha256_len_b3         = 59U,   
  k_sha256_len_b4         = 60U,   
  k_sha256_len_b5         = 61U,   
  k_sha256_len_b6         = 62U,   
  k_sha256_len_b7         = 63U,   
  k_sha256_len_hi         = 0x01U, 
  k_sha256_byte_shift     = 24U,   
} sha256_pad_t;

typedef enum : uint8_t {
  k_sha256_ssig0_r0 = 7U,  
  k_sha256_ssig0_r1 = 18U, 
  k_sha256_ssig0_sh = 3U,  
  k_sha256_ssig1_r0 = 17U, 
  k_sha256_ssig1_r1 = 19U, 
  k_sha256_ssig1_sh = 10U, 
  k_sha256_bsig1_r0 = 6U,  
  k_sha256_bsig1_r1 = 11U, 
  k_sha256_bsig1_r2 = 25U, 
  k_sha256_bsig0_r0 = 2U,  
  k_sha256_bsig0_r1 = 13U, 
  k_sha256_bsig0_r2 = 22U, 
  k_sha256_back15   = 15U, 
  k_sha256_back7    = 7U,  
} sha256_rot_t;

typedef enum : uint8_t {
  k_sha256_st_a = 0U, 
  k_sha256_st_b = 1U, 
  k_sha256_st_c = 2U, 
  k_sha256_st_d = 3U, 
  k_sha256_st_e = 4U, 
  k_sha256_st_f = 5U, 
  k_sha256_st_g = 6U, 
  k_sha256_st_h = 7U, 
} sha256_state_idx_t;

typedef struct {
  uint8_t key[k_ra8_key_vault_key_bytes]; 
} ra8_key_vault_slot_t;
 
static ra8_key_vault_slot_t s_vault[k_ra8_key_vault_slots];

typedef enum : uint16_t {
  k_kv_mac_key_128 = 16U, 
  k_kv_mac_key_256 = 32U, 
} ra8_kv_mac_key_len_t;

static uint8_t s_mac_key[k_ra8_key_vault_mac_key_bytes];

static uint16_t s_mac_key_len = 0U;
 
/* =============================================================================
 * Tiny SHA-256 (single-block, 32-byte input)
 * =============================================================================
 *
 * Implements just enough of FIPS 180-4 to compute SHA-256 over a
 * 32-byte input. Used by ra8_key_vault_sha256_xor_challenge to
 * scramble the key in a way that does not reveal the key bytes.
 *
 * The SHA-256 sponge is a transcription of the FIPS 180-4 spec.
 * Every magic number below comes directly from the standard;
 * giving them names would inflate the code without adding clarity.
 */
 
static const uint32_t k_sha256_k[64] = {
  0x428a2f98U, 0x71374491U, 0xb5c0fbcfU, 0xe9b5dba5U, 0x3956c25bU, 0x59f111f1U, 0x923f82a4U,
  0xab1c5ed5U, 0xd807aa98U, 0x12835b01U, 0x243185beU, 0x550c7dc3U, 0x72be5d74U, 0x80deb1feU,
  0x9bdc06a7U, 0xc19bf174U, 0xe49b69c1U, 0xefbe4786U, 0x0fc19dc6U, 0x240ca1ccU, 0x2de92c6fU,
  0x4a7484aaU, 0x5cb0a9dcU, 0x76f988daU, 0x983e5152U, 0xa831c66dU, 0xb00327c8U, 0xbf597fc7U,
  0xc6e00bf3U, 0xd5a79147U, 0x06ca6351U, 0x14292967U, 0x27b70a85U, 0x2e1b2138U, 0x4d2c6dfcU,
  0x53380d13U, 0x650a7354U, 0x766a0abbU, 0x81c2c92eU, 0x92722c85U, 0xa2bfe8a1U, 0xa81a664bU,
  0xc24b8b70U, 0xc76c51a3U, 0xd192e819U, 0xd6990624U, 0xf40e3585U, 0x106aa070U, 0x19a4c116U,
  0x1e376c08U, 0x2748774cU, 0x34b0bcb5U, 0x391c0cb3U, 0x4ed8aa4aU, 0x5b9cca4fU, 0x682e6ff3U,
  0x748f82eeU, 0x78a5636fU, 0x84c87814U, 0x8cc70208U, 0x90befffaU, 0xa4506cebU, 0xbef9a3f7U,
  0xc67178f2U,
};
 
static const uint32_t k_sha256_h0[8] = {
  0x6a09e667U,
  0xbb67ae85U,
  0x3c6ef372U,
  0xa54ff53aU,
  0x510e527fU,
  0x9b05688cU,
  0x1f83d9abU,
  0x5be0cd19U,
};

RA8_INTERNAL static uint32_t internal_rotr(uint32_t x, uint32_t n)
{
  return (x >> n) | (x << (32U - n));
}
 
/* internal_sha256_32 is split into
 * three helpers (build_block, schedule, compress). Each helper iterates a
 * fixed loop count with no data-dependent branches; the only inputs whose
 * values steer control flow are loop indices, which are compile-time
 * constants. Side-channel posture is identical to the monolithic form. */

RA8_INTERNAL static void internal_sha256_build_block(const uint8_t* in32, uint8_t* block)
{
  /* Build the 64-byte block: 32 input bytes, 0x80, zeros, then
   * the 64-bit length in bits at the end (SHA-256 uses BIG-endian
   * length). */
  for (uint32_t i = 0U; i < k_sha256_msg_bytes; ++i) {
    block[i] = in32[i];
  }
  block[k_sha256_pad_pos] = k_sha256_pad_marker;
  for (uint32_t i = k_sha256_pad_zero_start; i < k_sha256_len_b0; ++i) {
    block[i] = 0U;
  }
  /* Length = 32 bytes = 256 bits = 0x0100 big-endian. */
  block[k_sha256_len_b0] = 0U;
  block[k_sha256_len_b1] = 0U;
  block[k_sha256_len_b2] = 0U;
  block[k_sha256_len_b3] = 0U;
  block[k_sha256_len_b4] = 0U;
  block[k_sha256_len_b5] = 0U;
  block[k_sha256_len_b6] = k_sha256_len_hi;
  block[k_sha256_len_b7] = 0x00U;
}

RA8_INTERNAL static void internal_sha256_schedule(const uint8_t* block, uint32_t* w)
{
  for (uint32_t i = 0U; i < 16U; ++i) {
    w[i] = ((uint32_t)block[(i * 4U) + 0U] << k_sha256_byte_shift) |
           ((uint32_t)block[(i * 4U) + 1U] << 16U) | ((uint32_t)block[(i * 4U) + 2U] << 8U) |
           ((uint32_t)block[(i * 4U) + 3U]);
  }
  for (uint32_t i = 16U; i < k_sha256_words; ++i) {
    const uint32_t s0 = internal_rotr(w[i - k_sha256_back15], k_sha256_ssig0_r0) ^
                        internal_rotr(w[i - k_sha256_back15], k_sha256_ssig0_r1) ^
                        (w[i - k_sha256_back15] >> k_sha256_ssig0_sh);
    const uint32_t s1 = internal_rotr(w[i - 2U], k_sha256_ssig1_r0) ^
                        internal_rotr(w[i - 2U], k_sha256_ssig1_r1) ^
                        (w[i - 2U] >> k_sha256_ssig1_sh);
    w[i]              = w[i - 16U] + s0 + w[i - k_sha256_back7] + s1;
  }
}

RA8_INTERNAL static void internal_sha256_compress(const uint32_t* w, uint8_t* out32)
{
  uint32_t a = k_sha256_h0[k_sha256_st_a];
  uint32_t b = k_sha256_h0[k_sha256_st_b];
  uint32_t c = k_sha256_h0[k_sha256_st_c];
  uint32_t d = k_sha256_h0[k_sha256_st_d];
  uint32_t e = k_sha256_h0[k_sha256_st_e];
  uint32_t f = k_sha256_h0[k_sha256_st_f];
  uint32_t g = k_sha256_h0[k_sha256_st_g];
  uint32_t h = k_sha256_h0[k_sha256_st_h];
 
  for (uint32_t i = 0U; i < k_sha256_words; ++i) {
    const uint32_t s1 = internal_rotr(e, k_sha256_bsig1_r0) ^ internal_rotr(e, k_sha256_bsig1_r1) ^
                        internal_rotr(e, k_sha256_bsig1_r2);
    const uint32_t ch = (e & f) ^ (~e & g);
    const uint32_t temp1 = h + s1 + ch + k_sha256_k[i] + w[i];
    const uint32_t s0  = internal_rotr(a, k_sha256_bsig0_r0) ^ internal_rotr(a, k_sha256_bsig0_r1) ^
                         internal_rotr(a, k_sha256_bsig0_r2);
    const uint32_t maj = (a & b) ^ (a & c) ^ (b & c);
    const uint32_t temp2 = s0 + maj;
    h                    = g;
    g                    = f;
    f                    = e;
    e                    = d + temp1;
    d                    = c;
    c                    = b;
    b                    = a;
    a                    = temp1 + temp2;
  }
 
  const uint32_t hh[8] = {
    a + k_sha256_h0[k_sha256_st_a],
    b + k_sha256_h0[k_sha256_st_b],
    c + k_sha256_h0[k_sha256_st_c],
    d + k_sha256_h0[k_sha256_st_d],
    e + k_sha256_h0[k_sha256_st_e],
    f + k_sha256_h0[k_sha256_st_f],
    g + k_sha256_h0[k_sha256_st_g],
    h + k_sha256_h0[k_sha256_st_h],
  };
  for (uint32_t i = 0U; i < 8U; ++i) {
    out32[(i * 4U) + 0U] = (uint8_t)(hh[i] >> k_sha256_byte_shift);
    out32[(i * 4U) + 1U] = (uint8_t)(hh[i] >> 16U);
    out32[(i * 4U) + 2U] = (uint8_t)(hh[i] >> 8U);
    out32[(i * 4U) + 3U] = (uint8_t)(hh[i]);
  }
}

RA8_INTERNAL static void internal_sha256_32(const uint8_t* in32, uint8_t* out32)
{
  uint8_t  block[k_sha256_block_bytes];
  uint32_t w[k_sha256_words];
  internal_sha256_build_block(in32, block);
  internal_sha256_schedule(block, w);
  internal_sha256_compress(w, out32);
}
 
/* =============================================================================
 * Public API
 * =============================================================================
 */

ra8_err_t ra8_key_vault_init(void)
{
  for (uint16_t s = 0U; s < k_ra8_key_vault_slots; ++s) {
    for (uint16_t i = 0U; i < k_ra8_key_vault_key_bytes; ++i) {
      s_vault[s].key[i] = 0U;
    }
  }
  for (uint16_t i = 0U; i < k_ra8_key_vault_mac_key_bytes; ++i) {
    s_mac_key[i] = 0U;
  }
  s_mac_key_len = 0U;
  return k_ra8_ok;
}

ra8_err_t ra8_key_vault_store(uint16_t slot, const uint8_t* key)
{
  RA8_CHECK_NULL_PTR(key, s_tag, "store: key");
  if (slot >= k_ra8_key_vault_slots) {
    return k_ra8_err_invalid_arg;
  }
  for (uint16_t i = 0U; i < k_ra8_key_vault_key_bytes; ++i) {
    s_vault[slot].key[i] = key[i];
  }
  return k_ra8_ok;
}

ra8_err_t ra8_key_vault_sha256_xor_challenge(uint16_t slot, const uint8_t* challenge, uint8_t* out)
{
  RA8_CHECK_NULL_PTR(challenge, s_tag, "challenge: challenge");
  RA8_CHECK_NULL_PTR(out, s_tag, "challenge: out");
  if (slot >= k_ra8_key_vault_slots) {
    return k_ra8_err_invalid_arg;
  }
  uint8_t scratch[k_ra8_key_vault_key_bytes] = {};
  for (uint16_t i = 0U; i < k_ra8_key_vault_key_bytes; ++i) {
    scratch[i] = (uint8_t)(s_vault[slot].key[i] ^ challenge[i]);
  }
  internal_sha256_32(scratch, out);
  /* Wipe the key-XOR-challenge result from the secure stack before the frame is
   * reused. ra8_secure_memzero writes through a volatile pointer, so -- unlike the
   * plain zero loop it replaces, which the optimiser was free to elide as a dead
   * store (the old code even suppressed cppcheck's unreadVariable) -- the erase
   * is an observable side effect that survives -O2 (T5-12). */
  ra8_secure_memzero(scratch, (size_t)k_ra8_key_vault_key_bytes);
  return k_ra8_ok;
}
 
ra8_err_t ra8_key_vault_set_mac_key(const uint8_t* key, uint16_t key_len)
{
  RA8_CHECK_NULL_PTR(key, s_tag, "set_mac_key: key");
  if ((key_len != (uint16_t)k_kv_mac_key_128) && (key_len != (uint16_t)k_kv_mac_key_256)) {
    return k_ra8_err_invalid_arg;
  }
  for (uint16_t i = 0U; i < k_ra8_key_vault_mac_key_bytes; ++i) {
    s_mac_key[i] = (i < key_len) ? key[i] : 0U;
  }
  s_mac_key_len = key_len;
  return k_ra8_ok;
}
 
ra8_err_t ra8_key_vault_load_mac_key(uint8_t* out, uint16_t out_cap, uint16_t* out_len)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "load_mac_key: out");
  RA8_CHECK_NULL_PTR(out_len, s_tag, "load_mac_key: out_len");
  if (s_mac_key_len == 0U) {
    return k_ra8_err_not_found;
  }
  if (out_cap < s_mac_key_len) {
    return k_ra8_err_invalid_size;
  }
  for (uint16_t i = 0U; i < s_mac_key_len; ++i) {
    out[i] = s_mac_key[i];
  }
  *out_len = s_mac_key_len;
  return k_ra8_ok;
}
 
#else /* production build: neither RA8_INSECURE_STUB_CRYPTO nor RA8_OFF_TARGET */
 
/*
 * Fail-closed production variant. The software key store above is a placeholder
 * for a hardware-backed vault, so every entry point returns a hard error
 * (never k_ra8_ok). A production image that forgot to provide the real vault
 * therefore cannot store keys in unprotected SRAM or answer challenges from it.
 */
 
ra8_err_t ra8_key_vault_init(void)
{
  return k_ra8_err_not_supported;
}
 
ra8_err_t ra8_key_vault_store(uint16_t slot, const uint8_t* key)
{
  RA8_CHECK_NULL_PTR(key, s_tag, "store: key");
  (void)slot;
  return k_ra8_err_not_supported;
}
 
ra8_err_t ra8_key_vault_sha256_xor_challenge(uint16_t slot, const uint8_t* challenge, uint8_t* out)
{
  RA8_CHECK_NULL_PTR(challenge, s_tag, "challenge: challenge");
  RA8_CHECK_NULL_PTR(out, s_tag, "challenge: out");
  (void)slot;
  return k_ra8_err_not_supported;
}
 
ra8_err_t ra8_key_vault_set_mac_key(const uint8_t* key, uint16_t key_len)
{
  RA8_CHECK_NULL_PTR(key, s_tag, "set_mac_key: key");
  (void)key_len;
  return k_ra8_err_not_supported;
}
 
ra8_err_t ra8_key_vault_load_mac_key(uint8_t* out, uint16_t out_cap, uint16_t* out_len)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "load_mac_key: out");
  RA8_CHECK_NULL_PTR(out_len, s_tag, "load_mac_key: out_len");
  (void)out_cap;
  return k_ra8_err_not_supported;
}
 
#endif /* RA8_INSECURE_STUB_CRYPTO || RA8_OFF_TARGET */