lowRISC / lowRISC/opentitan

[kmac] KMAC entropy mode specification mismatch

Open
#27,526 2 comments 0 reactions 2 assignees View on GitHub

@AlexJones0 is already working on this.

Since Jul 15, 2025.

IP:kmac
Dominant language
SystemVerilog
Stars
3.6k
Forks
1.1k
Avg merge
2d 22h
Merged PRs (30d)
141

Description

Description

The KMAC specification describes that when using software-seeded entropy:

After this point, the PRNG can no longer be seeded by software - also after switching back into this mode from edn_mode. However, it is possible to switch to edn_mode.

It further suggests that whilst you can transition between edn_mode and sw_mode, that it is not possible to return to idle_mode without resetting:

After that point, the hardware cannot be made to return to idle_mode unless the module is reset.

The current kmac_entropy module does not match this behaviour - the entropy mode is latched in the StReset FSM state and is not intended to be changed without resetting the IP.

I believe that a further mismatch exists as whilst the spec suggests that "the hardware cannot be made to return to idle_mode", this does not appear to be the case. Consider the KMAC configured in EDN entropy mode:

  • Set the timer sufficiently small (e.g. timer=1, prescaler=0) or disable the Entropy complex to cause a transition to StRandErrWaitExpired through to StRandErr.
  • Process the error in software via CMD.err_processed to reset the KMAC to its StRandReset state.
  • So long as you remove the cfg_shadowed.entropy_ready bit before doing so, the KMAC is then in EntropyModeIdle, and can be reconfigured to any entropy mode, without doing a full reset of the KMAC IP.

The specification and/or RTL should be updated so that they do not conflict. Since the transition from edn_mode to sw_mode is a logical backup mechanism to account for potential issues in the entropy complex, it probably makes the most sense to retain this and add functionality for the hardware to switch from sw_mode to edn_mode, though this likely requires further discussion.

Furthermore, the ROM_EXT currently uses software-seeded entropy on the basis of SHAKE not requiring entropy, to avoid handling corner cases (also see this comment).

Currently, tests which use the KMAC but run after ROM_EXT are often thus configuring the KMAC to use EDN-sourced entropy, unaware that the hardware KMAC is still using SW-seeded entropy under the hood. This relates to issue #27045, where the kmac_error_conditions_test and kmac_entropy test both attempt to set a minimal KMAC entropy timeout value to get a timeout error, but are unable to in ROM_EXT environments since the KMAC IP is already locked into using software-seeded entropy.

In general, the latched entropy mode not being visible to software seems problematic in that software has no reliable way of determining how the KMAC is sourcing its entropy, or what state the KMAC entropy module is in. Software can read the currently configured mode, but there is nothing stopping software from configuring the KMAC to use software-seeded entropy, and then modifying the config to look like the KMAC is using EDN entropy with a timeout, even though the underlying hardware is not doing this at all.

Edit: I've thrown together a quick example to test & convince myself that the current KMAC does allow you to switch from EDN entropy mode to SW-seeded entropy, so long as entropy is not arriving fast enough. You can find that here.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.