What the documentation says · COLDCARD entropy incident

COLDCARD's documentation describes the intended entropy mechanism in enough detail to compare it with the implementation: an STM32 hardware generator, a secure-element-seeded PRNG, XOR mixing and SHA-256 whitening.

The affected implementation did not follow that data flow. This comparison records the difference without making an inference about what any individual knew at the time.

What the FAQ says

The FAQ captured on 1 August says the device primarily uses the STM32 hardware TRNG, XORs a PRNG seeded from SE1 and SE2 into that output, and then applies SHA-256 whitening. It describes the hardware source as measuring analogue transistor noise.

Documented design and affected execution

As documented

flowchart LR
  T["Hardware TRNG<br/>analogue transistor noise"] --> X(("XOR"))
  P["PRNG<br/>seeded at boot from<br/>SE1 and SE2 TRNGs"] --> X
  X --> W["SHA-256 whitening<br/>described as reducing bias"]
  W --> S["256-bit seed"]

  classDef n-safe stroke-width:1.5px
  class T,P,X,W,S n-safe

On affected firmware

flowchart LR
  T["Hardware TRNG"] -. "never reached<br/>the seed path" .-> X(("XOR"))
  P["MicroPython Yasmarang<br/>UID word, SysTick and RTC"] --> X
  N["libngu Yasmarang<br/>constants on Mk2/Mk3;<br/>at-most-32-bit reseed on Mk4 class"] --> X
  X --> W["SHA-256 whitening<br/>may diffuse visible bias;<br/>adds no entropy"]
  W --> S["Candidate space depends on<br/>model and attacker knowledge"]

  classDef n-act stroke-width:1.5px
  classDef n-plan stroke-width:1.5px
  class P,N,S n-act
  class W n-plan

In the documented design, a uniform hardware term independent of the PRNG would make the XOR output uniform even if the other input were predictable. Independence and successful hardware sampling are therefore important parts of the stated construction.

On affected firmware the STM32 hardware term was not reached through this call path. The XOR combined the MicroPython fallback with libngu's generator. Mk2 and Mk3 had no external reseed. On the normal Mk4-class boot path, one libngu state word was overwritten by a secure-element-derived value carrying at most 32 bits. The published candidate-space estimates differ according to how much of the remaining UID and timing state an attacker is assumed to know.

What whitening can and cannot establish

The FAQ gives an example in which an input has 10% ones and 90% zeros and says SHA-256 returns the output bit distribution to 50/50. A cryptographic hash is commonly used to diffuse visible input bias, but it does not make an arbitrary biased source exactly uniform or restore min-entropy that the source did not contain.

Whitening can mask bias, not entropy shortfall

A hash cannot create entropy. Feed SHA-256 a value drawn from a set of 2³² possibilities and the 256-bit result can occupy at most 2³² distinct outputs. Hash collisions can make that set smaller. The output bits can appear balanced while an attacker still has no more than the original candidate set to enumerate.

Output-side statistical tests do not establish which entropy source fed the hash. Detecting this substitution required tracing the call and linked symbol or performing a provenance-aware runtime test.

The documentation's dice statement

The FAQ capture made on 1 August 2026 also describes the value present before optional dice rolls are added.

"the entropy (about 2.5 bits per roll) will be added to the 256 bits of entropy already picked." COLDCARD documentation

The sentence states that 256 bits are already present before the rolls. That runtime property was not true for affected device-generated seeds. This archive verifies the wording as it appeared on 1 August 2026, after disclosure. When the sentence first appeared, and whether it was present during the affected period, remain open here: this archive has not yet checked Internet Archive copies of the FAQ for earlier states. Nor does the capture show how the wording affected individual decisions to use or skip dice.

Affected firmware did not establish 256 bits before dice

Block publishes conditional known-state cases down to 2^0 for Mk2/Mk3 and ≤2^32 for a successfully reseeded Mk4-class device, together with loose ceilings below 2^40.7 and 2^73.3. Coinkite and LLFOURN publish other scenarios near 40 and 72 bits. Talip's explicitly tentative Mk4 model reaches 2^88 under its most expansive RTC assumptions. The model register keeps these scenarios separate because they do not form one clean lower-to-upper interval. None is measured per-device entropy. In pure-dice generation, sufficient fair and secret rolls bypass the affected generator. In mixed mode, the affected value remains a prefix and the rolls add a separate source of uncertainty.

The dice code hashes roll symbols directly rather than feeding them through the 32-bit reseed path. The dice page distinguishes pure and mixed workflows and states the assumptions attached to each.

Documentation implications

Specific mechanisms can be checked. Naming the hardware source, mixing step and whitening step makes a source-level comparison possible.
A design description does not attest to a linked binary. Verifying source provenance requires following the call to the object that provides the symbol, and binary verification requires a separate reproducible build or image analysis.
The 256-bit statement is a runtime-property claim. Such claims can be tied to build-time checks or tests that fail when the named entropy source is not present.