Registers

Summary

NameOffsetLengthDescription
kmac.INTR_STATE0x04Interrupt State Register
kmac.INTR_ENABLE0x44Interrupt Enable Register
kmac.INTR_TEST0x84Interrupt Test Register
kmac.ALERT_TEST0xc4Alert Test Register
kmac.CFG_REGWEN0x104Register write enable for CFG_SHADOWED register.
kmac.CFG_SHADOWED0x144KMAC Configuration register.
kmac.CMD0x184KMAC/ SHA3 command register.
kmac.STATUS0x1c4KMAC/SHA3 Status register.
kmac.ENTROPY_CFG_LOCK0x204Software lock for the ENTROPY_CFG_SHADOWED register.
kmac.ENTROPY_CFG_REGWEN0x244Register write enable for ENTROPY_CFG_SHADOWED register.
kmac.ENTROPY_CFG_SHADOWED0x284Entropy Configuration register.
kmac.ENTROPY_SEED0x2c4Entropy Seed
kmac.ENTROPY_REFRESH_HASH_CNT0x304Entropy Refresh Counter
kmac.KEY_SHARE0_00x344KMAC Secret Key
kmac.KEY_SHARE0_10x384KMAC Secret Key
kmac.KEY_SHARE0_20x3c4KMAC Secret Key
kmac.KEY_SHARE0_30x404KMAC Secret Key
kmac.KEY_SHARE0_40x444KMAC Secret Key
kmac.KEY_SHARE0_50x484KMAC Secret Key
kmac.KEY_SHARE0_60x4c4KMAC Secret Key
kmac.KEY_SHARE0_70x504KMAC Secret Key
kmac.KEY_SHARE0_80x544KMAC Secret Key
kmac.KEY_SHARE0_90x584KMAC Secret Key
kmac.KEY_SHARE0_100x5c4KMAC Secret Key
kmac.KEY_SHARE0_110x604KMAC Secret Key
kmac.KEY_SHARE0_120x644KMAC Secret Key
kmac.KEY_SHARE0_130x684KMAC Secret Key
kmac.KEY_SHARE0_140x6c4KMAC Secret Key
kmac.KEY_SHARE0_150x704KMAC Secret Key
kmac.KEY_SHARE1_00x744KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_10x784KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_20x7c4KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_30x804KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_40x844KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_50x884KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_60x8c4KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_70x904KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_80x944KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_90x984KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_100x9c4KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_110xa04KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_120xa44KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_130xa84KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_140xac4KMAC Secret Key, 2nd share.
kmac.KEY_SHARE1_150xb04KMAC Secret Key, 2nd share.
kmac.KEY_LEN0xb44Secret Key length in bit.
kmac.PREFIX_00xb84cSHAKE Prefix register.
kmac.PREFIX_10xbc4cSHAKE Prefix register.
kmac.PREFIX_20xc04cSHAKE Prefix register.
kmac.PREFIX_30xc44cSHAKE Prefix register.
kmac.PREFIX_40xc84cSHAKE Prefix register.
kmac.PREFIX_50xcc4cSHAKE Prefix register.
kmac.PREFIX_60xd04cSHAKE Prefix register.
kmac.PREFIX_70xd44cSHAKE Prefix register.
kmac.PREFIX_80xd84cSHAKE Prefix register.
kmac.PREFIX_90xdc4cSHAKE Prefix register.
kmac.PREFIX_100xe04cSHAKE Prefix register.
kmac.ERR_CODE0xe44KMAC/SHA3 Error Code
kmac.STATE0x400512Keccak State (1600 bit) memory.
kmac.MSG_FIFO0x8002048Message FIFO.

INTR_STATE

Interrupt State Register

  • Offset: 0x0
  • Reset default: 0x0
  • Reset mask: 0x7

Fields

{"reg": [{"name": "kmac_done", "bits": 1, "attr": ["rw1c"], "rotate": -90}, {"name": "fifo_empty", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "kmac_err", "bits": 1, "attr": ["rw1c"], "rotate": -90}, {"bits": 29}], "config": {"lanes": 1, "fontsize": 10, "vspace": 120}}
BitsTypeResetName
31:3Reserved
2rw1c0x0kmac_err
1ro0x0fifo_empty
0rw1c0x0kmac_done

INTR_STATE . kmac_err

KMAC/SHA3 error occurred. ERR_CODE register shows the details

INTR_STATE . fifo_empty

The message FIFO is empty. This interrupt is raised only if the message FIFO is actually writable by software, i.e., if all of the following conditions are met: i) The KMAC block is not exercised by a hardware application interface. ii) The SHA3 block is in the Absorb state. iii) Software has not yet written the Process command to finish the absorption process. For the interrupt to be raised, the message FIFO must also have been full previously. Otherwise, the hardware empties the FIFO faster than software can fill it and there is no point in interrupting the software to inform it about the message FIFO being empty.

INTR_STATE . kmac_done

KMAC/SHA3 absorbing has been completed

INTR_ENABLE

Interrupt Enable Register

  • Offset: 0x4
  • Reset default: 0x0
  • Reset mask: 0x7

Fields

{"reg": [{"name": "kmac_done", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "fifo_empty", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "kmac_err", "bits": 1, "attr": ["rw"], "rotate": -90}, {"bits": 29}], "config": {"lanes": 1, "fontsize": 10, "vspace": 120}}
BitsTypeResetNameDescription
31:3Reserved
2rw0x0kmac_errEnable interrupt when INTR_STATE.kmac_err is set.
1rw0x0fifo_emptyEnable interrupt when INTR_STATE.fifo_empty is set.
0rw0x0kmac_doneEnable interrupt when INTR_STATE.kmac_done is set.

INTR_TEST

Interrupt Test Register

  • Offset: 0x8
  • Reset default: 0x0
  • Reset mask: 0x7

Fields

{"reg": [{"name": "kmac_done", "bits": 1, "attr": ["wo"], "rotate": -90}, {"name": "fifo_empty", "bits": 1, "attr": ["wo"], "rotate": -90}, {"name": "kmac_err", "bits": 1, "attr": ["wo"], "rotate": -90}, {"bits": 29}], "config": {"lanes": 1, "fontsize": 10, "vspace": 120}}
BitsTypeResetNameDescription
31:3Reserved
2wo0x0kmac_errWrite 1 to force INTR_STATE.kmac_err to 1.
1wo0x0fifo_emptyWrite 1 to force INTR_STATE.fifo_empty to 1.
0wo0x0kmac_doneWrite 1 to force INTR_STATE.kmac_done to 1.

ALERT_TEST

Alert Test Register

  • Offset: 0xc
  • Reset default: 0x80000000
  • Reset mask: 0x80000003

Fields

{"reg": [{"name": "recov_operation_err", "bits": 1, "attr": ["wo"], "rotate": -90}, {"name": "fatal_fault_err", "bits": 1, "attr": ["wo"], "rotate": -90}, {"bits": 29}, {"name": "regwen", "bits": 1, "attr": ["rw0c"], "rotate": -90}], "config": {"lanes": 1, "fontsize": 10, "vspace": 210}}
BitsTypeResetNameDescription
31rw0c0x1regwenWrite 0 to disable alert testing until the next reset.
30:2Reserved
1wo0x0fatal_fault_errWrite 1 to trigger one alert event of this kind.
0wo0x0recov_operation_errWrite 1 to trigger one alert event of this kind.

CFG_REGWEN

Register write enable for CFG_SHADOWED register.

  • Offset: 0x10
  • Reset default: 0x1
  • Reset mask: 0x1

Fields

{"reg": [{"name": "CFG_REGWEN", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 31}], "config": {"lanes": 1, "fontsize": 10, "vspace": 120}}
BitsTypeResetNameDescription
31:1Reserved
0ro0x1CFG_REGWENThis bit indicates whether the CFG_SHADOWED register can be updated by software (1) or not (0). This bit reads 0 if the Keccak core is operating as indicated in the STATUS register.

CFG_SHADOWED

KMAC Configuration register.

This register can only be updated when the Keccak core is idle. This is indicated by CFG_REGWEN reading as 1. If CFG_REGWEN reads as 0 (meaning the Keccak core is busy), writes to this register are ignored.

  • Offset: 0x14
  • Reset default: 0x0
  • Reset mask: 0x418133f
  • Register enable: CFG_REGWEN

Fields

{"reg": [{"name": "kmac_en", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "kstrength", "bits": 3, "attr": ["rw"], "rotate": -90}, {"name": "mode", "bits": 2, "attr": ["rw"], "rotate": -90}, {"bits": 2}, {"name": "msg_endianness", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "state_endianness", "bits": 1, "attr": ["rw"], "rotate": -90}, {"bits": 2}, {"name": "sideload", "bits": 1, "attr": ["rw"], "rotate": -90}, {"bits": 6}, {"name": "entropy_fast_process", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "msg_mask", "bits": 1, "attr": ["rw"], "rotate": -90}, {"bits": 5}, {"name": "en_unsupported_modestrength", "bits": 1, "attr": ["rw"], "rotate": -90}, {"bits": 5}], "config": {"lanes": 1, "fontsize": 10, "vspace": 290}}
BitsTypeResetName
31:27Reserved
26rw0x0en_unsupported_modestrength
25:21Reserved
20rw0x0msg_mask
19rw0x0entropy_fast_process
18:13Reserved
12rw0x0sideload
11:10Reserved
9rw0x0state_endianness
8rw0x0msg_endianness
7:6Reserved
5:4rw0x0mode
3:1rw0x0kstrength
0rw0x0kmac_en

CFG_SHADOWED . en_unsupported_modestrength

Enable Unsupported Mode and Strength configs.

SW may set this field for KMAC to move forward with unsupported Keccak Mode and Strength configurations, such as cSHAKE512.

If not set, KMAC won’t propagate the SW command (CmdStart) to the rest of the blocks (AppIntf, KMAC Core, SHA3).

CFG_SHADOWED . msg_mask

Message Masking with PRNG.

If 1, KMAC applies PRNG to the input messages to the Keccak module when KMAC mode is on.

CFG_SHADOWED . entropy_fast_process

Entropy Fast process mode.

If 1, entropy logic uses garbage data while not processing the KMAC key block. It will re-use previous entropy value and will not expand the entropy when it is consumed. Only it refreshes the entropy while processing the secret key block. This process should not be used if SCA resistance is required because it may cause side channel leakage.

CFG_SHADOWED . sideload

Sideloaded Key.

If 1, KMAC uses KeyMgr sideloaded key for SW initiated KMAC operation. KMAC uses the sideloaded key regardless of this configuration when KeyMgr initiates the KMAC operation for Key Derivation Function (KDF).

CFG_SHADOWED . state_endianness

State Endianness.

If 1 then each individual word in the STATE output register is converted to big-endian byte order. The order of the words in relation to one another is not changed. This setting does not affect how the state is interpreted during computation.

CFG_SHADOWED . msg_endianness

Message Endianness.

If 1 then each individual multi-byte value, regardless of its alignment, written to MSG_FIFO will be added to the message in big-endian byte order. If 0, each value will be added to the message in little-endian byte order. A message written to MSG_FIFO one byte at a time will not be affected by this setting. From a hardware perspective byte swaps are performed on a TL-UL word granularity.

CFG_SHADOWED . mode

Keccak hashing mode.

This module supports SHA3 main hashing algorithm and the part of its derived functions, SHAKE and cSHAKE with limitations. This field is to select the mode.

ValueNameDescription
0x0SHA3SHA3 hashing mode. It appends 2'b 10 to the end of msg
0x2SHAKESHAKE hashing mode. It appends 1111 to the end of msg
0x3cSHAKEcSHAKE hashing mode. It appends 00 to the end of msg

Other values are reserved.

CFG_SHADOWED . kstrength

Hashing Strength

3 bit field to select the security strength of SHA3 hashing engine. If mode field is set to SHAKE or cSHAKE, only 128 and 256 strength can be selected. Other value will result error when hashing starts.

ValueNameDescription
0x0L128128 bit strength. Keccak rate is 1344 bit
0x1L224224 bit strength. Keccak rate is 1152 bit
0x2L256256 bit strength. Keccak rate is 1088 bit
0x3L384384 bit strength. Keccak rate is 832 bit
0x4L512512 bit strength. Keccak rate is 576 bit

Other values are reserved.

CFG_SHADOWED . kmac_en

KMAC datapath enable.

If this bit is 1, the KMAC mode is active and the secret key is prepended to the incoming message.

CMD

KMAC/ SHA3 command register.

This register is to control the KMAC to start accepting message, to process the message, and to manually run additional keccak rounds at the end. Only at certain stage, the CMD affects to the control logic. It follows the sequence of

start –> process –> {run if needed –> } done

  • Offset: 0x18
  • Reset default: 0x0
  • Reset mask: 0x73f

Fields

{"reg": [{"name": "cmd", "bits": 6, "attr": ["r0w1c"], "rotate": 0}, {"bits": 2}, {"name": "entropy_req", "bits": 1, "attr": ["r0w1c"], "rotate": -90}, {"name": "hash_cnt_clr", "bits": 1, "attr": ["r0w1c"], "rotate": -90}, {"name": "err_processed", "bits": 1, "attr": ["r0w1c"], "rotate": -90}, {"bits": 21}], "config": {"lanes": 1, "fontsize": 10, "vspace": 150}}
BitsTypeResetName
31:11Reserved
10r0w1cxerr_processed
9r0w1cxhash_cnt_clr
8r0w1cxentropy_req
7:6Reserved
5:0r0w1cxcmd

CMD . err_processed

When error occurs and one of the state machine stays at Error handling state, SW may process the error based on ERR_CODE, then let FSM back to the reset state

CMD . hash_cnt_clr

Software can set this bit to 1 to manually clear ENTROPY_REFRESH_HASH_CNT.

CMD . entropy_req

Software can set this bit to 1 to manually trigger the reseeding of the internal PRNG when running in EDN Mode or in Software Mode. This will also clear ENTROPY_REFRESH_HASH_CNT.

After setting this bit, the STATUS.entropy_ready bit should read as 0 and the STATUS.entropy_reseeding bit as 1 indicating that a reseed operation is ongoing.

If ENTROPY_CFG_SHADOWED.ignore_cmd_entropy_req is set, this bit is ignored. If masking is disabled, this bit is ignored.

CMD . cmd

Issue a command to the KMAC/SHA3 IP. The command is sparse encoded. To prevent sw from writing multiple commands at once, the field is defined as enum.

ValueNameDescription
0x07startWriting 6’b000111 or dec 7 into this field when KMAC/SHA3 is in idle, KMAC/SHA3 begins its operation. If the mode is cSHAKE, before receiving the message, the hashing logic processes Function name string N and customization input string S first. If KMAC mode is enabled, additionally it processes secret key block.
0x32processWriting 6’b110010 or dec 50 into this field when KMAC/SHA3 began its operation and received the entire message, it computes the digest or signing.
0x2erunThe run field is used in the sponge squeezing stage. It triggers the keccak round logic to run full 24 rounds. This is optional and used when software needs more digest bits than the keccak rate. It only affects when the kmac/sha3 operation is completed.
0x35doneWriting 6’b110101 or dec 53 into this field completes the operation. The KMAC/SHA3 hashing engine clears the Keccak state and internal variables and goes back to Idle state for the next command. The command also releases the KMAC HWIP when SW has claimed it with the state_write command.
0x1cstopWriting 6’b011100 or dec 28 into this field when KMAC/SHA3 is receiving the message stops the sponge absorbing stage without appending any padding. The Keccak state then holds a valid intermediate sponge state, which SW can read from STATE to save the context. The message received since the last start or continue command must be a multiple of the Keccak rate. Otherwise the absorbing stage is stopped anyway, but the exposed state is not a valid context and ErrSwStopNotBlockAligned is reported. Once STATUS.sha3_stopped is set, or the kmac_done interrupt is raised, SW reads STATE and completes the operation with the done command, which clears the Keccak state. This command is not available when a sideloaded key is used, as saving the context would expose the key. The command is then discarded and ErrSwSaveRestoreSideload is reported.
0x1bstate_writeWriting 6’b011011 or dec 27 into this field when KMAC/SHA3 is idle claims the KMAC HWIP for SW such that it can write a previously saved context to the KMAC HWIP. The command also clears the Keccak state, so a restore always starts from a known state. SW resumes the operation with the continue command once the full context is written. If SW decides not to resume after all, the done command releases the KMAC HWIP again. This command is not available when a sideloaded key is used. The command is then discarded and ErrSwSaveRestoreSideload is reported.
0x29continueWriting 6’b101001 or dec 41 into this field after the state_write command resumes the sponge absorbing stage from the context that SW has written into STATE. Issuing it without claiming the KMAC HWIP first is discarded and reported as ErrSwCmdSequence. In contrast to the start command, the prefix and key are not processed again, as both are already part of the restored state. The KEY_SHARE0 and KEY_SHARE1 registers therefore do not need to be restored, but CFG_SHADOWED must hold the same configuration as before the context was saved. This command is not available when a sideloaded key is used. The command is then discarded and ErrSwSaveRestoreSideload is reported.

Other values are reserved.

STATUS

KMAC/SHA3 Status register.

  • Offset: 0x1c
  • Reset default: 0x4001
  • Reset mask: 0x3030df1f

Fields

{"reg": [{"name": "sha3_idle", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "sha3_absorb", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "sha3_squeeze", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "sha3_stopped", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "state_write", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 3}, {"name": "fifo_depth", "bits": 5, "attr": ["ro"], "rotate": -90}, {"bits": 1}, {"name": "fifo_empty", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "fifo_full", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 4}, {"name": "entropy_ready", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "entropy_reseeding", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 6}, {"name": "ALERT_FATAL_FAULT", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "ALERT_RECOV_CTRL_UPDATE_ERR", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 2}], "config": {"lanes": 1, "fontsize": 10, "vspace": 290}}
BitsTypeResetName
31:30Reserved
29ro0x0ALERT_RECOV_CTRL_UPDATE_ERR
28ro0x0ALERT_FATAL_FAULT
27:22Reserved
21ro0x0entropy_reseeding
20ro0x0entropy_ready
19:16Reserved
15roxfifo_full
14ro0x1fifo_empty
13Reserved
12:8roxfifo_depth
7:5Reserved
4roxstate_write
3roxsha3_stopped
2roxsha3_squeeze
1roxsha3_absorb
0ro0x1sha3_idle

STATUS . ALERT_RECOV_CTRL_UPDATE_ERR

An update error has not occurred (0) or has occurred (1) in the shadowed Control or Entropy Control Registers. KMAC operation needs to be restarted by re-writing the Control or Entropy Control Registers.

STATUS . ALERT_FATAL_FAULT

No fatal fault has occurred inside the KMAC unit (0). A fatal fault has occurred and the KMAC unit needs to be reset (1), Examples for such faults include i) TL-UL bus integrity fault ii) storage errors in the shadow registers iii) errors in the message, round, or key counter iv) any internal FSM entering an invalid state v) an error in the redundant lfsr

STATUS . entropy_reseeding

If 1, the internal PRNG is currently performing a reseed operation via EDN or waiting for software to provide a new seed.

If masking is disabled, this bit always reads as 0.

STATUS . entropy_ready

If 1, the internal PRNG is ready. If 0, the internal PRNG is either not operating in EDN Mode or Software Mode (i.e., Entropy Boot Mode is active), or the PRNG is currently performing a reseed operation via EDN or waiting for software to provide a new seed via ENTROPY_SEED. While this bit reads 0, the module will reject KMAC mode operation:

  • If software tries to trigger a KMAC mode operation, a ErrSwHashingWithoutEntropyReady error is returned.
  • If an application interface tries to trigger a KMAC mode operation, a service rejected error is returned.

If masking is disabled, this bit matches the inverse of the ENTROPY_CFG_SHADOWED.entropy_boot_mode bit.

STATUS . fifo_full

Message FIFO Full indicator

STATUS . fifo_empty

Message FIFO Empty indicator.

The FIFO’s Pass parameter is set to 1'b 1. So, by default, if the SHA engine is ready, the write data to FIFO just passes through.

In this case, fifo_depth remains 0. fifo_empty, however, lowers the value to 0 for a cycle, then goes back to the empty state, 1.

See the “Message FIFO” section in the spec for the reason.

STATUS . fifo_depth

Count of occupied entries in the message FIFO.

STATUS . state_write

If 1, SW has claimed the KMAC HWIP with the state_write command and writes to STATE are accepted. SW must poll this bit after issuing the command and before writing the context.

The bit clears again when SW leaves the state with the continue or the done command.

STATUS . sha3_stopped

If 1, SHA3 has stopped the sponge absorbing stage for a context switch. In this stage, SW can read the STATE to save the context. The absorbing stage is resumed by restoring the STATE and issuing the continue command.

STATUS . sha3_squeeze

If 1, SHA3 completes sponge absorbing stage. In this stage, SW can manually run the hashing engine.

STATUS . sha3_absorb

If 1, SHA3 is receiving message stream and processing it

STATUS . sha3_idle

If 1, SHA3 hashing engine is in idle state.

ENTROPY_CFG_LOCK

Software lock for the ENTROPY_CFG_SHADOWED register.

By setting this register to 1, software can lock the current content of the ENTROPY_CFG_SHADOWED register until the next reset.

  • Offset: 0x20
  • Reset default: 0x0
  • Reset mask: 0x1

Fields

{"reg": [{"name": "ENTROPY_CFG_LOCK", "bits": 1, "attr": ["rw1s"], "rotate": -90}, {"bits": 31}], "config": {"lanes": 1, "fontsize": 10, "vspace": 180}}
BitsTypeResetName
31:1Reserved
0rw1s0x0ENTROPY_CFG_LOCK

ENTROPY_CFG_LOCK . ENTROPY_CFG_LOCK

This bit indicates whether software has locked the current content of the ENTROPY_CFG_SHADOWED register (1) or not (0). Whether the ENTROPY_CFG_SHADOWED register can be updated, is indicated in ENTROPY_CFG_REGWEN. Once this bit is set to 1, ENTROPY_CFG_REGWEN keeps reading as 0 until the next reset.

ENTROPY_CFG_REGWEN

Register write enable for ENTROPY_CFG_SHADOWED register.

  • Offset: 0x24
  • Reset default: 0x1
  • Reset mask: 0x1

Fields

{"reg": [{"name": "ENTROPY_CFG_REGWEN", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 31}], "config": {"lanes": 1, "fontsize": 10, "vspace": 200}}
BitsTypeResetName
31:1Reserved
0ro0x1ENTROPY_CFG_REGWEN

ENTROPY_CFG_REGWEN . ENTROPY_CFG_REGWEN

This bit indicates whether the ENTROPY_CFG_SHADOWED register can be updated by software (1) or not (0). If ENTROPY_CFG_LOCK is 1, this bit reads as 0. This bit also reads 0 if the internal PRNG is currently being reseeded or if the Keccak core is operating as indicated in the STATUS register.

ENTROPY_CFG_SHADOWED

Entropy Configuration register.

This register can only be updated when the Keccak core is idle and if write access has not yet been locked down. This is indicated by ENTROPY_CFG_REGWEN reading as 1. If ENTROPY_CFG_REGWEN reads as 0 (meaning the Keccak core is busy and/or write access has been locked down), writes to this register are ignored.

If masking is disabled, only the Entropy Boot Mode field of this register is relevant and the remaining fields are ignored.

  • Offset: 0x28
  • Reset default: 0x1
  • Reset mask: 0x3ff0007
  • Register enable: ENTROPY_CFG_REGWEN

Fields

{"reg": [{"name": "entropy_boot_mode", "bits": 1, "attr": ["rw0c"], "rotate": -90}, {"name": "entropy_mode", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "ignore_cmd_entropy_req", "bits": 1, "attr": ["rw"], "rotate": -90}, {"bits": 13}, {"name": "edn_mode_refresh_threshold", "bits": 10, "attr": ["rw"], "rotate": -90}, {"bits": 6}], "config": {"lanes": 1, "fontsize": 10, "vspace": 280}}
BitsTypeResetName
31:26Reserved
25:16rw0x0edn_mode_refresh_threshold
15:3Reserved
2rw0x0ignore_cmd_entropy_req
1rw0x0entropy_mode
0rw0c0x1entropy_boot_mode

ENTROPY_CFG_SHADOWED . edn_mode_refresh_threshold

EDN Mode Refresh Threshold

The number of KMAC messages after which the module automatically triggers a reseed operation when running in EDN Mode. Note that the automatic reseed operation is not triggered when ending the message processing, but after processing the KMAC key block. If an automatic reseed operation is triggered, the Keccak core can continue processing the message in parallel to the reseed operation.

If this field reads as 0, no automatic reseed operations are triggered in EDN Mode.

ENTROPY_CFG_SHADOWED . ignore_cmd_entropy_req

If this bit is set, writes to CMD.entropy_req are ignored. This can be useful for locking down the PRNG configuration and prevent further reseed operations, e.g., if later software stages aren’t trusted.

ENTROPY_CFG_SHADOWED . entropy_mode

Entropy Mode

Using this field, software can configure the non-boot mode of operation of the internal pseudo-random number generator (PRNG).

The value of this field is only relevant if ENTROPY_CFG_SHADOWED.entropy_boot_mode reads as 0.

ValueNameDescription
0x0edn_modeReceive fresh entropy from EDN for reseeding the internal PRNG. This entropy mode is to be used for regular operation. When this mode is activated first after reset, the STATUS.entropy_reseeding bit is set to 1 and the module requests fresh entropy from EDN for reseeding the internal PRNG. Once the reseed operation finishes, the STATUS.entropy_ready bit is set to 1 and the module can start processing commands. Depending on CFG_SHADOWED, the internal PRNG is then used for (re-)masking inputs (prefix, key, message) and intermediate results of the Keccak core. The module will then automatically reseed the internal PRNG with fresh entropy from EDN every ENTROPY_CFG_SHADOWED.edn_mode_refresh_threshold messages in KMAC mode. More precisely, automatic reseed operations are always triggered directly after the key absorption phase. How close the module is to automatically trigger a reseed operation can be inferred from ENTROPY_REFRESH_HASH_CNT. Alternatively, software can manually initiate reseeding operations using CMD.entropy_req while the module is idle. This will also clear ENTROPY_REFRESH_HASH_CNT. Before enabling this mode, software has to make sure the entropy complex is actually running. Otherwise, the module will wait indefinitely for entropy and the STATUS.entropy_ready bit will remain 0, meaning the module won’t operate in KMAC mode. To change from this mode to sw_mode, software has to first configure the mode and then trigger a reseed operation using CMD.entropy_req.
0x1sw_modeReceive entropy from software for reseeding the internal PRNG. This entropy mode is a fall-back option to be used if the entropy complex is not available. When this mode is activated first after reset, the STATUS.entropy_reseeding bit is set to 1 and the module waits for software to write the ENTROPY_SEED register 6 times. Upon each write, the written value is loaded into the corresponding state chunk of the PRNG. After the last write operation, the STATUS.entropy_ready bit is set to 1 and the module can start processing commands. Depending on CFG_SHADOWED, the internal PRNG is then used for (re-)masking inputs (prefix, key, message) and intermediate results of the Keccak core. After this point, software can manually initiate reseeding operations using CMD.entropy_req while the module is idle. This will also clear ENTROPY_REFRESH_HASH_CNT. To change from this mode to edn_mode, software has to first configure the mode and then trigger a reseed operation using CMD.entropy_req.

ENTROPY_CFG_SHADOWED . entropy_boot_mode

Entropy Boot Mode

If this field reads 1, the internal pseudo-random number generator (PRNG) is operating in boot mode irrespective of the value of ENTROPY_CFG_SHADOWED.entropy_mode. The sole purpose of the Entropy Boot Mode is to enable the initial ROM_CTRL operation right after coming out of reset.

In this mode, the internal PRNG is not reseeded with fresh entropy, nor updated while the Keccak core operates. It should therefore not be used after this very initial boot phase and software should disable the Entropy Boot Mode and configure the desired ENTROPY_CFG_SHADOWED.entropy_mode value as early as possible.

Note that the first time after reset that this field is set to 0, an initial reseed operation of the internal PRNG is triggered. Because the ENTROPY_CFG_SHADOWED register cannot be updated while reseed operations are ongoing, software must configure ENTROPY_CFG_SHADOWED.entropy_mode before or with the same register write that disables ENTROPY_CFG_SHADOWED.entropy_boot_mode.

ENTROPY_SEED

Entropy Seed

Entropy seed register for the internal PRNG.

If ENTROPY_CFG_SHADOWED.entropy_boot_mode reads 0, if ENTROPY_CFG_SHADOWED.entropy_mode is set to sw_mode, and if STATUS.entropy_reseeding reads 1, software can write this register 6 times. Upon each write, the written value is loaded into the corresponding state chunk of the internal PRNG.

After writing the register 6 times, the STATUS.entropy_reseeding bit drops to 0, the PRNG is ready to deliver randomness to the Keccak core which is indicated by the STATUS.entropy_ready bit being set. After this point, another reseed operation can be initiated via CMD.entropy_req.

  • Offset: 0x2c
  • Reset default: 0x0
  • Reset mask: 0xffffffff

Fields

{"reg": [{"name": "seed", "bits": 32, "attr": ["wo"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}
BitsTypeResetNameDescription
31:0woxseed32-bit chunk of the entropy generator seed

ENTROPY_REFRESH_HASH_CNT

Entropy Refresh Counter

KMAC entropy can be refreshed after the given threshold KMAC operations run. If the KMAC hash counter ENTROPY_REFRESH_HASH_CNT hits (GTE) the configured threshold ENTROPY_CFG_SHADOWED.edn_mode_refresh_threshold, the entropy module in the KMAC IP requests new seed to EDN and reset the KMAC hash counter.

If the threshold is 0, the refresh by the counter does not work. And the counter is only reset by the CMD.hash_cnt_clr CSR bit.

  • Offset: 0x30
  • Reset default: 0x0
  • Reset mask: 0x3ff

Fields

{"reg": [{"name": "hash_cnt", "bits": 10, "attr": ["ro"], "rotate": 0}, {"bits": 22}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}
BitsTypeResetNameDescription
31:10Reserved
9:0ro0x0hash_cntHash (KMAC) counter

KEY_SHARE0

KMAC Secret Key

KMAC secret key can be up to 512 bit. Order of the secret key is: key[512:0] = {KEY15, KEY14, … , KEY0};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

Current KMAC supports up to 512 bit secret key. It is the sw responsibility to keep upper bits of the secret key to 0.

  • Reset default: 0x0
  • Reset mask: 0xffffffff
  • Register enable: CFG_REGWEN

Instances

NameOffset
KEY_SHARE0_00x34
KEY_SHARE0_10x38
KEY_SHARE0_20x3c
KEY_SHARE0_30x40
KEY_SHARE0_40x44
KEY_SHARE0_50x48
KEY_SHARE0_60x4c
KEY_SHARE0_70x50
KEY_SHARE0_80x54
KEY_SHARE0_90x58
KEY_SHARE0_100x5c
KEY_SHARE0_110x60
KEY_SHARE0_120x64
KEY_SHARE0_130x68
KEY_SHARE0_140x6c
KEY_SHARE0_150x70

Fields

{"reg": [{"name": "key", "bits": 32, "attr": ["wo"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}
BitsTypeResetNameDescription
31:0woxkey32-bit chunk of up-to 512-bit Secret Key

KEY_SHARE1

KMAC Secret Key, 2nd share.

KMAC secret key can be up to 512 bit. Order of the secret key is: key[512:0] = {KEY15, KEY14, … , KEY0};

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

Current KMAC supports up to 512 bit secret key. It is the sw responsibility to keep upper bits of the secret key to 0.

  • Reset default: 0x0
  • Reset mask: 0xffffffff
  • Register enable: CFG_REGWEN

Instances

NameOffset
KEY_SHARE1_00x74
KEY_SHARE1_10x78
KEY_SHARE1_20x7c
KEY_SHARE1_30x80
KEY_SHARE1_40x84
KEY_SHARE1_50x88
KEY_SHARE1_60x8c
KEY_SHARE1_70x90
KEY_SHARE1_80x94
KEY_SHARE1_90x98
KEY_SHARE1_100x9c
KEY_SHARE1_110xa0
KEY_SHARE1_120xa4
KEY_SHARE1_130xa8
KEY_SHARE1_140xac
KEY_SHARE1_150xb0

Fields

{"reg": [{"name": "key", "bits": 32, "attr": ["wo"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}
BitsTypeResetNameDescription
31:0woxkey32-bit chunk of up-to 512-bit Secret Key

KEY_LEN

Secret Key length in bit.

This value is used to make encoded secret key in KMAC. KMAC supports certain lengths of the secret key. Currently it supports 128b, 192b, 256b, 384b, and 512b secret keys.

  • Offset: 0xb4
  • Reset default: 0x0
  • Reset mask: 0x7
  • Register enable: CFG_REGWEN

Fields

{"reg": [{"name": "len", "bits": 3, "attr": ["wo"], "rotate": 0}, {"bits": 29}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}
BitsTypeResetName
31:3Reserved
2:0wo0x0len

KEY_LEN . len

Key length choice

ValueNameDescription
0x0Key128Key length is 128 bit.
0x1Key192Key length is 192 bit.
0x2Key256Key length is 256 bit.
0x3Key384Key length is 384 bit.
0x4Key512Key length is 512 bit.

Other values are reserved.

PREFIX

cSHAKE Prefix register.

Prefix including Function Name N and Customization String S. The SHA3 assumes this register value is encoded as: encode_string(N) || encode_string(S) || 0. It means that the software can freely decide the length of N or S based on the given Prefix register size 320bit. 320bit is determined to have 32-bit of N and up to 256-bit of S + encode of their length.

It is SW responsibility to fill the register with encoded value that is described at Section 2.3.2 String Encoding in NIST SP 800-185 specification.

Order of Prefix is: prefix[end:0] := {PREFIX(N-1), …, PREFIX(1), PREFIX(0) }

The registers are allowed to be updated when the engine is in Idle state. If the engine computes the hash, it discards any attempts to update the secret keys and report an error.

  • Reset default: 0x0
  • Reset mask: 0xffffffff
  • Register enable: CFG_REGWEN

Instances

NameOffset
PREFIX_00xb8
PREFIX_10xbc
PREFIX_20xc0
PREFIX_30xc4
PREFIX_40xc8
PREFIX_50xcc
PREFIX_60xd0
PREFIX_70xd4
PREFIX_80xd8
PREFIX_90xdc
PREFIX_100xe0

Fields

{"reg": [{"name": "prefix", "bits": 32, "attr": ["rw"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}
BitsTypeResetNameDescription
31:0rw0x0prefix32-bit chunk of Encoded NS Prefix

ERR_CODE

KMAC/SHA3 Error Code

  • Offset: 0xe4
  • Reset default: 0x0
  • Reset mask: 0xffffffff

Fields

{"reg": [{"name": "err_code", "bits": 32, "attr": ["ro"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}
BitsTypeResetName
31:0ro0x0err_code

ERR_CODE . err_code

If the kmac_err interrupt occurs, this register has information on the error cause. Bits 31:24 contain the error code (please refer to err_code_e in hw/ip/kmac/rtl/kmac_pkg.sv) for the encoding, and bits 23:0 contain additional debug information. This register does not get cleared when the kmac_err interrupt state gets cleared.

STATE

Keccak State (1600 bit) memory.

The software can get the processed digest by reading this memory region. Unlike MSG_FIFO, STATE memory space sees the addr[9:0]. If Masking feature is enabled, the software reads two shares from this memory space.

Software can write to the register to restore a previously saved context. Writes are only accepted once software claimed the KMAC HWIP with the state_write command and while the hashing engine is idle, which STATUS.state_write reports. Writes at any other time are acknowledged on the bus and ignored.

Writes must be full 32-bit word writes. Sub-word writes are answered with a bus error, as a partial write cannot be applied to the Keccak state.

0x400 - 0x4C7: State share 0x500 - 0x5C7: Mask share of the state, 0 if EnMasking = 0

  • Word Aligned Offset Range: 0x400to0x5fc
  • Size (words): 128
  • Access: rw
  • Byte writes are not supported.

MSG_FIFO

Message FIFO.

Any write operation to this window will be appended to MSG_FIFO. SW can simply write bytes/words to any address within this address range. Ordering and packing of the incoming bytes/words are handled internally. Therefore, the least significant 12 bits of the address are ignored.

  • Word Aligned Offset Range: 0x800to0xffc
  • Size (words): 512
  • Access: wo
  • Byte writes are supported.