OpenTitan Documentation

KMAC smoke test will contain a number of rounds, and acts as a base for many other tests. In each round, we run a full KMAC hashing operation:

• Randomly enable interrupts, operation mode (SHA3/SHAKE/CSHAKE/KMAC), key length (if applicable), constraining all settings to be legal.
• Set function name to "KMAC" and set customization string as empty if applicable.
• Randomly set endianness of input msg and internal keccak state.
• Randomly provide a sideloaded key, do not set cfg.sideload.
• Set output length between 1-keccak_rate bytes if applicable.
• Randomly select either SW or EDN as the source of entropy
• Trigger KMAC to start absorbing input message.
  • During absorption stage randomly read from STATE window, expect 0.
• Write message to MSG_FIFO window, maximum length of 32 bytes.
• Check SHA3 engine status.
• Trigger KMAC to finish absorbing stage, check kmac_done is set and status.squeeze is set.
• Read output digest, and compare against output from reference C++ model.
  • In masked configuration: both shares are XORed to get unmasked result digest.
  • In unmasked configuration: Share1 is the result digest, Share2 should be 0.
• Signal cmd.done to tell KMAC to clear internal state.
• Try reading output digest again, confirm that it is 0.

This test, and all other tests in the testplan, will be checked for correctness in two different ways:

• first, a DPI-C model is used to check that the correct digest value is produced
• a cycle-accurate model is implemented in the scoreboard to provide constant checks during each hash operation and ensure that internal state is being updated correctly

Verify the reset values as indicated in the RAL specification.

• Write all CSRs with a random value.
• Apply reset to the DUT as well as the RAL model.
• Read each CSR and compare it against the reset value. it is mandatory to replicate this test for each reset that affects all or a subset of the CSRs.
• It is mandatory to run this test for all available interfaces the CSRs are accessible from.
• Shuffle the list of CSRs first to remove the effect of ordering.

Verify accessibility of CSRs as indicated in the RAL specification.

• Loop through each CSR to write it with a random value.
• Read the CSR back and check for correctness while adhering to its access policies.
• It is mandatory to run this test for all available interfaces the CSRs are accessible from.
• Shuffle the list of CSRs first to remove the effect of ordering.

Verify no aliasing within individual bits of a CSR.

• Walk a 1 through each CSR by flipping 1 bit at a time.
• Read the CSR back and check for correctness while adhering to its access policies.
• This verify that writing a specific bit within the CSR did not affect any of the other bits.
• It is mandatory to run this test for all available interfaces the CSRs are accessible from.
• Shuffle the list of CSRs first to remove the effect of ordering.

Verify no aliasing within the CSR address space.

• Loop through each CSR to write it with a random value
• Shuffle and read ALL CSRs back.
• All CSRs except for the one that was written in this iteration should read back the previous value.
• The CSR that was written in this iteration is checked for correctness while adhering to its access policies.
• It is mandatory to run this test for all available interfaces the CSRs are accessible from.
• Shuffle the list of CSRs first to remove the effect of ordering.

Verify random reset during CSR/memory access.

• Run csr_rw sequence to randomly access CSRs
• If memory exists, run mem_partial_access in parallel with csr_rw
• Randomly issue reset and then use hw_reset sequence to check all CSRs are reset to default value
• It is mandatory to run this test for all available interfaces the CSRs are accessible from.

Verify regwen CSR and its corresponding lockable CSRs.

• Randomly access all CSRs
• Test when regwen CSR is set, its corresponding lockable CSRs become read-only registers

Note:

• If regwen CSR is HW read-only, this feature can be fully tested by common CSR tests - csr_rw and csr_aliasing.
• If regwen CSR is HW updated, a separate test should be created to test it.

This is only applicable if the block contains regwen and locakable CSRs.

Verify accessibility of all memories in the design.

• Run the standard UVM mem walk sequence on all memories in the RAL model.
• It is mandatory to run this test from all available interfaces the memories are accessible from.

Verify partial-accessibility of all memories in the design.

• Do partial reads and writes into the memories and verify the outcome for correctness.
• Also test outstanding access on memories

Same as the smoke test, except with a message of up to 100KB. Max firmware input size for KMAX is around 392KB, but this is too large for a DV simulation. Average input size from firmware would be around 60-100KB, so we use 100KB as a max input size for DV, but will enable easy extensibility for emulation testing where we can enable much larger messages. Allow output length to vary up to 1KB (for XOF functions). If output length is greater than keccak_rate bytes, keccak rounds will be run manually to squeeze extra output data. Set function name as "KMAC" and enable full randomization of customization string (if applicable).

This is the same as the long_message test, except we burst-write chunks of the message into the msg_fifo, and disable intermediate status/CSR checks.

These tests drive NIST test vectors for SHA3/SHAKE/KMAC into the design and check the output against the expected digest values.

Same as the smoke test, except we set cfg.sideload and provide a valid sideloaded key as well as a valid SW-provided key. KMAC should operate on the sideloaded key regardless of the cfg_shadowed.sideload field value.

Test that the Keymgr/ROM/LC can all initiate a KMAC operation through the application interface - Keymgr uses KMAC hash, while ROM/LC use CShake. Use an array of kmac_app_agents to send message data to the KMAC and to control the hashing logic, and set cfg.sideload if the Keymgr is enabled. The result digest sent to the kmac_app_agent will be compared against the result from the DPI reference model. In addition, read from the STATE window afterwards and confirm that this access is blocked and will return 0.

Basd on the kmac_app test, this test will send partial data from application interface by sending strb with values other than 8'hFF. Because the scoreboard is cycle accurate and does not support this feature, this test will not check status and intr_state registers, but will check other registers and all interface data including digest.

Test entropy interface for KMAC.

This test randomly chooses to execute either a SW-controlled hash or a hash from the App interface. All configuration fields are left as is, but now we will request EDN entropy by setting the following registers with random value:

• "cmd.entropy_req": Request an EDN entropy
• "cmd.hash_cnt_clear": Clear the entropy_refresh_hash_cnt
• "entropy_refresh_threshold_shadowed": The threshold when KMAC should request an EDN entropy

In masked mode, scoreboard will check:

• Register entropy_refresh_hash_cnt value
• KMAC requests EDN at the correct time

In unmasked mode, scoreboard will check:

• Register entropy_refresh_hash_cnt always returns 0

Try several error sequences:

• Update key/prefix/config during absorption/process/squeeze stage.
• Write msg to msg_fifo during process/squeeze stage
• When in KMAC mode, set the function name to not "KMAC"
• Incorrect SHA3 control flow:
  • Issue Process/Run/Done cmds before issuing Start
  • Issue Run/Done before issuing Process
  • Issue Start after issuing Process
  • If squeezing data, issue Start/Process after issuing Run
• Incorrect KMAC configurations (e.g. set KMAC strength as 512).
• Provide software inputs during operation of the application interface

// TODO: Not all of these errors have been supported yet, and more errors might be // added later. // So this might be split into several error tests later on.

Test kmac responses correctly when keymgr app sends request but key is not valid. Stimulus:

• Configure kmac and send keymgr request, but did not set valid bit for keymgr key input.
• Wait randomly clock cycles.
• Issue err_processed, then wait for the keymgr interface handshake to finish.
• Repeat the above sequence a few times.
• Issue correct kmac request from app or sw interface.

Check:

• Check error related registers including err_code, status, and interrupt.
• Check keymgr interface responses with all zero digests and error bit is set.
• Check kmac can resume normal functionalities after processing this error case.

Test kmac responses correctly when EDN response timeout. Based on kmac app sequence, this sequence configures kmac to ensure an EDN timeout error by writing entropy_period.wait_timer and entropy_period.prescaler registers. Check:

• Check error related registers including err_code, status, and interrupt.
• Check keymgr interface responses with error bit sets to 1.
• Check kmac can resume normal functionalities after processing this error case.
• Check timeout error will not trigger if the entropy_mode is set to SW, or masking is disabled.

Test kmac responses correctly when entropy mode is configured incorrectly. Based on kmac edn_timeout sequence, this sequence write incorrect ral.cfg_shadowed.entropy_mode before entropy is fetched. Check:

• Check error related registers including err_code, status, and interrupt.
• Check keymgr interface responses with error bit sets to 1.
• Check kmac can resume normal functionalities after processing this error case.
• Check timeout error will not trigger if masking is disabled.

Test kmac responses correctly when entropy_ready field is not set. Based on kmac app sequence, this sequence does not write 1 to ral.cfg_shadowed.entropy_ready field before a kmac operation. Check:

• If masking is enabled and the kmac operation is EDN mode:
  • If it is a SW operation, check error related registers including err_code, status, and interrupt.
  • If it is an APP operation, check keymgr interface responses with error bit sets to 1.
• If masking is not enabled or the operation does not require entropy:
  • Check no error triggered.

Randomly set lc_escalate_en to value that is not Off during Kmac operations.

Checks:

• Fatal alert fires continuously until reset is issued.
• Status fields: alert_fatal_fault is set to 1 and sha3_idle is reset to 0.
• Kmac does not accept any SW or APP requests.
• Digest window always output all 0s.

• Combine above sequences in one test to run sequentially, except csr sequence and some error tests that disabled scoreboard.
• Randomly add reset between each sequence

Verify common intr_test CSRs that allows SW to mock-inject interrupts.

• Enable a random set of interrupts by writing random value(s) to intr_enable CSR(s).
• Randomly "turn on" interrupts by writing random value(s) to intr_test CSR(s).
• Read all intr_state CSR(s) back to verify that it reflects the same value as what was written to the corresponding intr_test CSR.
• Check the cfg.intr_vif pins to verify that only the interrupts that were enabled and turned on are set.
• Clear a random set of interrupts by writing a randomly value to intr_state CSR(s).
• Repeat the above steps a bunch of times.

Verify common alert_test CSR that allows SW to mock-inject alert requests.

• Enable a random set of alert requests by writing random value to alert_test CSR.
• Check each alert_tx.alert_p pin to verify that only the requested alerts are triggered.
• During alert_handshakes, write alert_test CSR again to verify that: If alert_test writes to current ongoing alert handshake, the alert_test request will be ignored. If alert_test writes to current idle alert handshake, a new alert_handshake should be triggered.
• Wait for the alert handshakes to finish and verify alert_tx.alert_p pins all sets back to 0.
• Repeat the above steps a bunch of times.

Access out of bounds address and verify correctness of response / behavior

Drive unsupported requests via TL interface and verify correctness of response / behavior. Below error cases are tested bases on the TLUL spec

• TL-UL protocol error cases
  • invalid opcode
  • some mask bits not set when opcode is PutFullData
  • mask does not match the transfer size, e.g. a_address = 0x00, a_size = 0, a_mask = 'b0010
  • mask and address misaligned, e.g. a_address = 0x01, a_mask = 'b0001
  • address and size aren't aligned, e.g. a_address = 0x01, a_size != 0
  • size is greater than 2
• OpenTitan defined error cases
  • access unmapped address, expect d_error = 1 when devmode_i == 1
  • write a CSR with unaligned address, e.g. a_address[1:0] != 0
  • write a CSR less than its width, e.g. when CSR is 2 bytes wide, only write 1 byte
  • write a memory with a_mask != '1 when it doesn't support partial accesses
  • read a WO (write-only) memory
  • write a RO (read-only) memory
  • write with instr_type = True

Drive back-to-back requests without waiting for response to ensure there is one transaction outstanding within the TL device. Also, verify one outstanding when back- to-back accesses are made to the same address.

Access CSR with one or more bytes of data. For read, expect to return all word value of the CSR. For write, enabling bytes should cover all CSR valid fields.

Verify shadowed registers' update error.

• Randomly pick a shadowed register in the DUT.
• Write it twice with different values.
• Verify that the update error alert is triggered and the register value remains unchanged.
• Verify the update_error status register field is set to 1.
• Repeat the above steps a bunch of times.

Verify reading a shadowed register will clear its staged value.

• Randomly pick a shadowed register in the DUT.
• Write it once and read it back to clear the staged value.
• Then write it twice with the same new value (but different from the previous step).
• Read it back to verify the new value and ensure that the update error alert did not trigger.
• Verify the update_error status register field remains the same value.
• Repeat the above steps a bunch of times.

Verify shadowed registers' storage error.

• Randomly pick a shadowed register in the DUT.
• Backdoor write to shadowed or committed flops to create a storage fatal alert.
• Check if fatal alert continuously fires until reset.
• Verify that all other frontdoor write attempts are blocked during the storage error.
• Verify that storage_error status register field is set to 1.
• Reset the DUT.
• Read all CSRs to ensure the DUT is properly reset.
• Repeat the above steps a bunch of times.

Verify toggle shadowed_rst_n pin can trigger storage error.

• Randomly drive shadowed_rst_n pin to low or rst_n pin to low.
• check if any registers have been written before the reset. If so check if storage error fatal alert is triggered.
• Check status register.
• Drive shadowed_rst_n pin or rst_n pin back to high.
• If fatal alert is triggered, reset the DUT.
• Read all CSRs to ensure the DUT is properly reset.
• Repeat the above steps a bunch of times.

Run shadow_reg_update_error sequence in parallel with csr_rw sequence.

• Randomly select one of the above sequences.
• Apply csr_rw sequence in parallel but disable the csr_access_abort to ensure all shadowed registers' write/read to be executed without aborting.
• Repeat the above steps a bunch of times.

Verify that the data integrity check violation generates an alert.

• Randomly inject errors on the control, data, or the ECC bits during CSR accesses. Verify that triggers the correct fatal alert.
• Inject a fault at the onehot check in u_reg.u_prim_reg_we_check and verify the corresponding fatal alert occurs

Verify the countermeasure(s) BUS.INTEGRITY.

Verify global LC_ESCALATE_EN mubi

Verify the countermeasure(s) SW_KEY.KEY.MASKING.

Verify the key from KeyMgr is sideloaded.

Verify the countermeasure(s) CFG_SHADOWED.CONFIG.SHADOW.

Verify the countermeasure(s) FSM.SPARSE.

Verify the countermeasure(s) CTR.REDUN.

Verify the countermeasure(s) PACKER.CTR.REDUN.

Verify the countermeasure(s) CFG_SHADOWED.CONFIG.REGWEN.

Verify the countermeasure(s) FSM.GLOBAL_ESC.

Verify the countermeasure(s) FSM.LOCAL_ESC.

Verify the countermeasure(s) LOGIC.INTEGRITY.

Verify the countermeasure(s) ABSORBED.CTRL.INTEGRITY

Verify the countermeasure(s) SW_CMD.CTRL.INTEGRITY

Measure the throughput of the various hashing calculations and make sure they correspond to the expected throughput range for the design.

This test runs 3 parallel threads - stress_all, tl_errors and random reset. After reset is asserted, the test will read and check all valid CSR registers.

Covers several scenarios related to the app interface:

• A single data beat is sent
• All partial data lengths have been seen (only applies to the last data beat)
• Errors are reported through this interface
• Done signal is sent while keccak rounds are currently active/inactive

Note that this covergroup will be duplicated once per app interface.

Covers several scenarios related to the app interface and cfg_shadowed register value:

• Hash_mode field value.
• Kmac_en field value.
• Kstrength field value.

These sw register settings should not affect kmac app interface calculation. Note that this covergroup will be duplicated once per app interface.

Covers that the KMAC can handle seeing a CmdProcess command during the following sets of scenarios:

• various msgfifo status (full/empty/in between)
• while keccak rounds are currently active/inactive

Covers that all valid configuration settings for the KMAC have been tested. Individual config settings that will be covered include:

• hashing mode (sha3/shake/kmac)
• security strength (128/224/256/384/512)
• key length (128/192/256/384/512)
• message endianness enable/disable
• digest endianness enable/disable
• XOF mode when using KMAC hashing All valid combinations of the above will also be crossed.

Covers that EDN entropy can be received by KMAC while keccak rounds are active/inactive, crossed with a few entropy configuration values (fast entropy, etc...).

Cover the values for the entropy_period register's prescaler and wait_timer fields. Cross these field ranges with whether the entropy EDN mode is on or off.

Covers all error scenarios:

• ErrKeyNotValid: covers that secret key is invalid when KeyMgr initiates App operation
• ErrSwPushedMsgFifo: covers that SW writes the msgfifo while App interface is active
• ErrSwIssuedCmdInAppActive: covers that SW writes all possible commands to the KMAC while App interface is active
• ErrWaitTimerExpired: covers that the KMAC timed out while waiting for EDN entropy
• ErrIncorrectEntropyMode: covers that incorrect entropy modes are detected by the KMAC
• ErrUnexpectedModeStrength: covers that 128-bit strength is seen for SHA3, and all but 128/256 bit strengths are seen for XOF functions
• ErrIncorrectFunctionName: covers that the function name is configured incorrectly when KMAC mode is enabled
• ErrSwCmdSequence: covers that SW issues commands to the KMAC out of order

Covers various input message length ranges, to ensure that KMAC can operate successfully on different sized messages. The minimum tested msg length is 0 bytes, and the maximum length is 10_000 bytes, we will cover that an acceptable distribution of lengths has been seen, and specifically cover some corner cases (like length 0).

Covers that all possible fifo statuses have been seen when running different hash operations (like sha3/shake/cshake/kmac), such as various fifo depths, fifo full, and fifo empty.

Covers that the msgfifo has been written using all possible TLUL masks.

Similar to the msg_len_cg, we also want to cover various output digest lengths to ensure that KMAC can successfully produce outputs of varying sizes. Note that this only applies to XOF functions, as SHA3 functions have a fixed output length.

The prefix used for CSHAKE and KMAC (function_name + customization_string) are only allowed to be valid alphabet letters, or a space character. This covergroup covers that all of these characters have appeared in a prefix value.

Cover each lockable reg field with these 2 cases:

• When regwen = 1, a different value is written to the lockable CSR field, and a read occurs after that.
• When regwen = 0, a different value is written to the lockable CSR field, and a read occurs after that.

This is only applicable if the block contains regwen and locakable CSRs.

Covers that all sha3-related status fields have eventually been seen.

Cover all shadow register errors for each register field.

For all register fields within the shadowed register, this coverpoint covers the following errors:

• Update error
• Storage error

Covers that the KMAC sees scenarios where the sideloaded key is provided and should be used (en_sideload==1, app_mode==AppKeymgr), and scenarios where the sideloaded key is provided but should not be used.

Covers that the state windows have been read using all possible TLUL masks.

Cover the following error cases on TL-UL bus:

• TL-UL protocol error cases.
• OpenTitan defined error cases, refer to testpoint tl_d_illegal_access.

Cover all kinds of integrity errors (command, data or both) and cover number of error bits on each integrity check.

Cover the kinds of integrity errors with byte enabled write on memory if applicable: Some memories store the integrity values. When there is a subword write, design re-calculate the integrity with full word data and update integrity in the memory. This coverage ensures that memory byte write has been issued and the related design logic has been verfied.