secure_trng.c

Go to the documentation of this file.

 
#include <stdint.h>
 
#include "ra8_check.h"
#include "ra8_err.h"
#include "secure_trng_internal.h"
 
static const char* s_tag = "SECTRNG";
 
/*
 * Fail-closed stub-crypto gate (issue #180). The xorshift64* core below is a
 * DETERMINISTIC PRNG masquerading as a TRNG -- predictable "random" bytes were
 * the #1 severity finding in the security audit (predictable keys). It is only
 * safe under 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 predictable entropy can never be
 * drawn. scripts/checks/check_stub_crypto_guarded.py enforces that this guard
 * stays wrapped around the insecure body.
 */
#if defined(RA8_INSECURE_STUB_CRYPTO) || defined(RA8_OFF_TARGET)

typedef enum : uint64_t {
  k_xorshift_seed       = 0x9E3779B97F4A7C15ULL, 
  k_xorshift_multiplier = 0x2545F4914F6CDD1DULL, 
} ra8_secure_trng_consts64_t;
 
typedef enum : uint8_t {
  k_xorshift_shift_a = 12U, 
  k_xorshift_shift_b = 25U, 
  k_xorshift_shift_c = 27U, 
  k_byte_bits        = 8U,  
  k_bytes_per_u64    = 8U,  
} ra8_secure_trng_consts8_t;
 
typedef enum : uint32_t {
  k_byte_mask = 0xFFU, 
} ra8_secure_trng_consts32_t;

static uint64_t s_state = k_xorshift_seed;

static uint64_t internal_xorshift64(void)
{
  uint64_t x = s_state;
  x ^= x >> k_xorshift_shift_a;
  x ^= x << k_xorshift_shift_b;
  x ^= x >> k_xorshift_shift_c;
  s_state = x;
  return x * k_xorshift_multiplier;
}

ra8_err_t priv_ra8_secure_trng_reset(void)
{
  s_state = k_xorshift_seed;
  return k_ra8_ok;
}

ra8_err_t priv_ra8_secure_trng_read(uint8_t* out, uint32_t len)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "trng_read: out");
  if ((len == 0U) || (len > (uint32_t)k_ra8_secure_trng_max_bytes)) {
    return k_ra8_err_invalid_arg;
  }
  uint32_t written = 0U;
  /* Loop bound is the per-call cap (NASA Rule 2). */
  while (written < len) {
    const uint64_t word = internal_xorshift64();
    /* Inner loop bound is constant 8. */
    for (uint32_t b = 0U; (b < (uint32_t)k_bytes_per_u64) && (written < len); ++b) {
      out[written] = (uint8_t)((word >> (b * (uint32_t)k_byte_bits)) & k_byte_mask);
      ++written;
    }
  }
  return k_ra8_ok;
}
 
#else /* production build: neither RA8_INSECURE_STUB_CRYPTO nor RA8_OFF_TARGET */
 
/*
 * Fail-closed production variant. Without a real RSIP TRNG backend the
 * deterministic PRNG above must never run, so both entry points return a hard
 * error (never k_ra8_ok). A production image that forgot to provide real
 * entropy therefore cannot silently draw predictable "random" bytes.
 */
 
ra8_err_t priv_ra8_secure_trng_reset(void)
{
  return k_ra8_err_not_supported;
}
 
ra8_err_t priv_ra8_secure_trng_read(uint8_t* out, uint32_t len)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "trng_read: out");
  (void)len;
  return k_ra8_err_not_supported;
}
 
#endif /* RA8_INSECURE_STUB_CRYPTO || RA8_OFF_TARGET */