lowRISC / lowRISC/opentitan

[cryptolib] KMAC driver progress tracking

Open
#16,410 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Earlgrey-PROD Triaged SW:cryptolib
Dominant language
SystemVerilog
Stars
3.6k
Forks
1.1k
Avg merge
2d 22h
Merged PRs (30d)
141

Description

With #16180, KMAC driver implements SHA-3/SHAKE/cSHAKE/KMAC, however there is still a list of improvements to be done. The idea is to keep track of these small issues and address them in follow-up PRs.

Non-exhaustive list, in an arbitrary order:

- [ ] Revisit default configuration. In particular check that internal timer values are working. https://github.com/lowRISC/opentitan/pull/16180#discussion_r1022532627
- [x] Address memory aliasing violations (when writing key, msg, and prefix blocks to registers). https://github.com/lowRISC/opentitan/pull/16180#discussion_r1022593434
- [ ] Verify that entropy mode is correctly configured and `entropy_ready` is correctly set. Since `entropy_ready` triggers the internal FSM of kmac_entropy, it needs to be set in a timely fashion.
- [x] Move towards high-level crypto API (e.g. provide one-shot `kmac()`, `shake()` calls, accept keys in masked/blinded form etc.).
- [x] Revisit error checks in the driver, provide functions to clear errors and flush out KMAC.
- [X] Use consistent status types for error return types.
- [x] More extensive testing with varying key_len, msg_len, digest_len, and customization string parameters. Once KMAC driver implementation is stable, use the same structs and clean up the testing side.
- See if [on-device testing](https://github.com/lowRISC/opentitan/pull/16906#discussion_r1061835953) can be done,
- [Add checks for XKCP](https://github.com/lowRISC/opentitan/pull/16906#discussion_r1055788164).
- [x] When connecting things to cryptolib's API, also bridge similar relevant libraries besides KMAC. For example, `otcrypto_hash` should interact with KMAC driver for `SHA-3` calls, but `SHA-2` should also be glued to the same function.
- [x] Optimize writing to `MSG_FIFO` (ref: #16909).
- [x] Implement sideload support for KMAC.

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.

Research direction

Read PR #16180 and its discussion first, then inspect the KMAC driver areas related to default configuration and entropy mode. Verify that internal timer values and entropy_ready behavior are correct, and use the existing testing references to confirm the driver’s behavior. Done means the remaining unchecked improvements are addressed and their tests or verification evidence are recorded.

Written by the indexing model from the issue text.

Assessment

Domain
cryptography, embedded-iot
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.