docs: why RNG clock errors don't invalidate RNG_DR
What the developer wrote
Authored by scgbckbone
docs: why RNG clock errors don't invalidate RNG_DR
What changed, and why it matters
This commit only adds explanatory comments to two source files about why the COLDCARD firmware ignores certain hardware random-number-generator clock-error flags. It does not change any code behavior. The comments cite ST documentation saying these clock errors do not affect the quality of random numbers and that a dead clock is still caught by a data-ready timeout. There is no security-relevant code change.
No action required. This is a documentation-only change. If reviewing for security, verify separately that the cited ST documentation and errata accurately support the design decision to ignore CEIS/CECS.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff adds identical block comments in stm32/COLDCARD_MK4/rng.c and stm32/mk4-bootloader/rng.c just before the existing RNG_SEED_ERROR_MASK definition. The comments document that CEIS/CECS (clock-error interrupt/status flags) are deliberately not included in the error mask, referencing RM0432 section 32.3.7 and ST errata ES0250/ES0335. No logic, macros, function bodies, or control flow are modified.
Changed components
stm32/COLDCARD_MK4/rng.cstm32/mk4-bootloader/rng.cInspect captured patch +15 / −0
### stm32/COLDCARD_MK4/rng.c
@@ -53,6 +53,13 @@ static void rng_init(void) {
#define RNG_TIMEOUT_MS (10)
#define RNG_MAX_ATTEMPTS (3)
+
+// Clock-error flags (CEIS/CECS) are intentionally ignored: per RM0432
+// section 32.3.7, "the clock error has no impact on generated random
+// numbers", and ST's errata (ES0250/ES0335) confirm a clock error neither
+// stops generation nor invalidates RNG_DR when DRDY is set. A dead clock
+// still fails closed via the DRDY timeout below. CEIS is left set on
+// purpose: clearing it is a no-op while RNG interrupts stay disabled.
#define RNG_SEED_ERROR_MASK (RNG_SR_SEIS | RNG_SR_SECS)
static uint32_t last_value;
### stm32/mk4-bootloader/rng.c
@@ -7,6 +7,14 @@
#include "stm32l4xx_hal.h"
#define RNG_MAX_ATTEMPTS (3)
+
+// Clock-error flags (CEIS/CECS) are intentionally ignored: per RM0432
+// section 32.3.7, "the clock error has no impact on generated random
+// numbers", and ST's errata (ES0250/ES0335) confirm a clock error neither
+// stops generation nor invalidates RNG_DR when DRDY is set. A dead clock
+// still fails closed via the intentionally unbounded DRDY wait below.
+// CEIS is left set on purpose: clearing it is a no-op while RNG interrupts
+// stay disabled.
#define RNG_SEED_ERROR_MASK (RNG_SR_SEIS | RNG_SR_SECS)
// Recover from a seed error.Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.