Registers

Summary

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}}

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}}

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}}

ALERT_TEST

Alert Test Register

• Offset: 0xc
• Reset default: 0x0
• Reset mask: 0x3

Fields

{"reg": [{"name": "recov_operation_err", "bits": 1, "attr": ["wo"], "rotate": -90}, {"name": "fatal_fault_err", "bits": 1, "attr": ["wo"], "rotate": -90}, {"bits": 30}], "config": {"lanes": 1, "fontsize": 10, "vspace": 210}}

CFG_REGWEN

Controls the configurability of CFG_SHADOWED register.

This register ensures the contents of CFG_SHADOWED register cannot be changed by the software while the KMAC/SHA3 is in operation mode.

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

Fields

{"reg": [{"name": "en", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 31}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}

CFG_SHADOWED

KMAC Configuration register.

This register is updated when the hashing engine is in Idle. If the software updates the register while the engine computes, the updated value will be discarded.

• Offset: 0x14
• Reset default: 0x0
• Reset mask: 0x51b133f
• 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": 3}, {"name": "entropy_mode", "bits": 2, "attr": ["rw"], "rotate": -90}, {"bits": 1}, {"name": "entropy_fast_process", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "msg_mask", "bits": 1, "attr": ["rw"], "rotate": -90}, {"bits": 3}, {"name": "entropy_ready", "bits": 1, "attr": ["rw"], "rotate": -90}, {"bits": 1}, {"name": "en_unsupported_modestrength", "bits": 1, "attr": ["rw"], "rotate": -90}, {"bits": 5}], "config": {"lanes": 1, "fontsize": 10, "vspace": 290}}

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 . entropy_ready

Entropy Ready status.

Software sets this field to allow the entropy generator in KMAC to fetch the entropy and run.

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 . entropy_mode

Entropy Mode

Using this field, software can configure mode of operation of the internal pseudo-random number generator (PRNG). For the hardware to actually switch to an entropy mode other than the default idle_mode, software further needs to set the CFG_SHADOWED.entropy_ready bit. After that point, the hardware cannot be made to return to idle_mode unless the module is reset.

Other values are reserved.

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.

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.

Other values are reserved.

CFG_SHADOWED . kmac_en

KMAC datapath enable.

If this bit is 1, the incoming message is processed in KMAC with the secret key.

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}}

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

If writes 1, it clears the hash (KMAC) counter in the entropy module

CMD . entropy_req

SW triggered Entropy Request

If writes 1 to this field

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.

Other values are reserved.

STATUS

KMAC/SHA3 Status register.

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

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}, {"bits": 5}, {"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}, {"name": "ALERT_FATAL_FAULT", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "ALERT_RECOV_CTRL_UPDATE_ERR", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 14}], "config": {"lanes": 1, "fontsize": 10, "vspace": 290}}

STATUS . ALERT_RECOV_CTRL_UPDATE_ERR

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

STATUS . ALERT_FATAL_FAULT

No fatal fault has occurred inside the KMAC unit (0). A fatal fault has occured 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 . 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 . 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_PERIOD

Entropy Timer Periods.

• Offset: 0x20
• Reset default: 0x0
• Reset mask: 0xffff03ff
• Register enable: CFG_REGWEN

Fields

{"reg": [{"name": "prescaler", "bits": 10, "attr": ["rw"], "rotate": 0}, {"bits": 6}, {"name": "wait_timer", "bits": 16, "attr": ["rw"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}

ENTROPY_PERIOD . wait_timer

EDN request wait timer.

The entropy module in KMAC waits up to this field in the timer pulse after it sends request to EDN module. If the timer expires, the entropy module moves to an error state and notifies to the system.

If there is a pending EDN request during wait timer update, then this update is delayed until the EDN request is complete.

If 0, the entropy module waits the EDN response always. If EDN does not respond in this configuration, the software shall reset the IP.

ENTROPY_PERIOD . prescaler

EDN Wait timer prescaler.

EDN Wait timer has 16 bit value. The timer value is increased when the timer pulse is generated. Timer pulse is raises when the number of the clock cycles hit this prescaler value.

The exact period of the timer pulse is unknown as the KMAC input clock may contain jitters.

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_REFRESH_THRESHOLD_SHADOWED, 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: 0x24
• Reset default: 0x0
• Reset mask: 0x3ff
• Register enable: CFG_REGWEN

Fields

{"reg": [{"name": "hash_cnt", "bits": 10, "attr": ["ro"], "rotate": 0}, {"bits": 22}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}

ENTROPY_REFRESH_THRESHOLD_SHADOWED

Entropy Refresh Threshold

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_REFRESH_THRESHOLD_SHADOWED, 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: 0x28
• Reset default: 0x0
• Reset mask: 0x3ff
• Register enable: CFG_REGWEN

Fields

{"reg": [{"name": "threshold", "bits": 10, "attr": ["rw"], "rotate": 0}, {"bits": 22}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}

ENTROPY_SEED

Entropy Seed

Entropy seed register for the integrated entropy generator.

If CFG_SHADOWED.entropy_mode is set to sw_mode, software first needs to set CFG_SHADOWED.entropy_ready. Then, software needs to write the ENTROPY_SEED register 9 times. Upon each write, the written value is loaded into the corresponding state chunk of the entropy generator.

After writing the ENTROPY_SEED register 9 times, the entropy generator will start its operation. After this point, writing this register has no longer any effect.

• 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}}

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

Instances

Fields

{"reg": [{"name": "key", "bits": 32, "attr": ["wo"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}

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

Instances

Fields

{"reg": [{"name": "key", "bits": 32, "attr": ["wo"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}

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: 0xb0
• 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}}

KEY_LEN . len

Key length choice

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

Instances

Fields

{"reg": [{"name": "prefix", "bits": 32, "attr": ["rw"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}

ERR_CODE

KMAC/SHA3 Error Code

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

Fields

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

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.

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

• Word Aligned Offset Range: 0x400to0x5fc
• Size (words): 128
• Access: ro
• 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.