Programmer’s Guide
Initialization
The software can update the KMAC/SHA3 configurations only when the IP is in the idle state.
The software should check STATUS.sha3_idle
before updating the configurations.
The software must first program CFG_SHADOWED.msg_endianness
and CFG_SHADOWED.state_endianness
at the initialization stage.
These determine the byte order of incoming messages (msg_endianness) and the Keccak state output (state_endianness).
Software Initiated KMAC/SHA3 process
This section describes the expected software process to run the KMAC/SHA3 HWIP.
At first, the software configures CFG_SHADOWED.kmac_en
for KMAC operation.
If KMAC is enabled, the software should configure CFG_SHADOWED.mode
to cSHAKE and CFG_SHADOWED.kstrength
to 128 or 256 bit security strength.
The software also updates PREFIX
registers if cSHAKE mode is used.
Current design does not convert cSHAKE mode to SHAKE even if PREFIX
is empty string.
It is the software’s responsibility to change the CFG_SHADOWED.mode
to SHAKE in case of empty PREFIX
.
The KMAC/SHA3 HWIP uses PREFIX
registers as it is.
It means that the software should update PREFIX
with encoded values.
If CFG_SHADOWED.kmac_en
is set, the software should update the secret key.
The software prepares two shares of the secret key and selects its length in KEY_LEN
then writes the shares of the secret key to KEY_SHARE0
and KEY_SHARE1
.
The two shares of the secret key are the values that represent the secret key value when they are XORed together.
The software can XOR the unmasked secret key with entropy.
The XORed value is a share and the entropy used is the other share.
After configuring, the software notifies the KMAC/SHA3 engine to accept incoming messages by issuing Start command into CMD
.
If Start command is not issued, the incoming message is discarded.
If KMAC is enabled, the software pushes the right_encode(output_length)
value at the end of the message.
For example, if the desired output length is 256 bit, the software writes 0x00020100
to MSG_FIFO.
After the software pushes all messages, it issues Process command to CMD
for SHA3 engine to complete the sponge absorbing process.
SHA3 hashing engine pads the incoming message as defined in the SHA3 specification.
After the SHA3 engine completes the sponge absorbing step, it generates kmac_done
interrupt.
Or the software can poll the STATUS.squeeze
bit until it becomes 1.
In this stage, the software may run the Keccak round manually.
If the desired digest length is greater than the Keccak rate, the software issues Run command for the Keccak round logic to run one full round after the software reads the current available Keccak state.
At this stage, KMAC/SHA3 does not raise an interrupt when the Keccak round completes the software initiated manual run.
The software should check STATUS.squeeze
register field for the readiness of STATE
value.
After the software reads all the digest values, it issues Done command to CMD
register to clear the internal states.
Done command clears the Keccak state, FSM in SHA3 and KMAC, and a few internal variables.
Secret key and other software programmed values won’t be reset.
Endianness
This KMAC HWIP operates in little-endian. Internal SHA3 hashing engine receives in 64-bit granularity. The data written to SHA3 is assumed to be little endian.
The software may write/read the data in big-endian order if CFG_SHADOWED.msg_endianness
or CFG_SHADOWED.state_endianness
is set.
If the endianness bit is 1, the data is assumed to be big-endian.
So, the internal logic byte-swap the data.
For example, when the software writes 0xDEADBEEF
with endianness as 1, the logic converts it to 0xEFBEADDE
then writes into MSG_FIFO.
The software managed secret key, and the prefix are always little-endian values.
For example, if the software configures the function name N
in KMAC operation, it writes encode_string("KMAC")
.
The encode_string("KMAC")
represents 0x01 0x20 0x4b 0x4d 0x41 0x43
in byte order.
The software writes 0x4d4b2001
into PREFIX0
and 0x????4341
into PREFIX1
.
Upper 2 bytes can vary depending on the customization input string S
.
EDN Entropy Mode
For regular operation, CFG_SHADOWED.entropy_mode
should be set to EDN mode.
In this mode, the module automatically reseeds the internal PRNG with fresh entropy from EDN after every ENTROPY_REFRESH_THRESHOLD_SHADOWED
key absorption phases in KMAC mode.
Alternatively, software can manually initiate reseeding operations using the CMD.entropy_req
bit while the module is idle.
Preventing potential deadlocks in EDN mode
Under normal operating conditions, the SHA3 engine will process data a lot faster than software can push it to the Message FIFO. However, the Message FIFO may run full while the SHA3 engine is busy. In particular, this might happen because KMAC is waiting for fresh entropy from EDN. If software then tries to push further data to the Message FIFO, the processor will get stalled and if the entropy is not delivered (on time), the system may deadlock (see Empty and Full status for details).
To avoid this deadlock scenario, software should either:
- Manually trigger PRNG reseed operations after ensuring the entropy complex is up and running (recommended), or
- Check the Message FIFO depth before pushing data.
Since the latter option can be inconvenient for software, especially when processing long messages, manually triggering PRNG reseed operations is the recommended approach. In the following, both approaches are outlined in more detail.
Manually triggering PRNG reseeds
Since automatic reseeds of the internal PRNG are always triggered after the key absorption phase in KMAC mode (CFG_SHADOWED.kmac_en
set to 1), and since every message in KMAC mode has only one such phase, it is sufficient for software to check the ENTROPY_REFRESH_HASH_CNT
register after finishing a KMAC message.
If the value of ENTROPY_REFRESH_HASH_CNT
gets sufficiently close to the value of ENTROPY_REFRESH_THRESHOLD_SHADOWED
, software should:
- Ensure that the entropy complex is running.
- Check that the KMAC module is idle by reading the
STATUS.sha3_idle
bit. - Trigger a manual reseed operation by setting the
CMD.entropy_req
bit. - Configure the module to process a message in cSHAKE mode (but not in KMAC mode).
More precisely, set
CFG_SHADOWED.mode
to0x3
andCFG_SHADOWED.kmac_en
to 0. - Configure the module to use the PRNG and block any hashing operation if the PRNG is not ready by setting
CFG_SHADOWED.entropy_fast_process
to 0. - Send the
start
command to theCMD
register. The SHA3 engine will start loading and hashing the function nameN
and the customization stringS
first. - Send the
process
command to theCMD
register. - Wait for the
STATUS.sha3_squeeze
bit to get set. Due to the ongoing reseed operation, theSTATUS.sha3_squeeze
bit should remain 0 for an extended period of time. - Send the
done
command to theCMD
register to finish processing.
The ENTROPY_REFRESH_HASH_CNT
register should now read as 0.
Note however that if the manual reseed operation is triggered while the KMAC module is busy, the reseed operation may get skipped despite the hash counter being cleared back to 0.
Checking Message FIFO depth before pushing data
Alternatively, software can avoid ever pushing data into the Message FIFO while the FIFO is full by regularly checking the FIFO depth. In particular, software can then:
- Check the FIFO depth
STATUS.fifo_depth
. This represents the number of entry slots currently occupied in the FIFO. - Calculate the remaining size as (
<max number of FIFO entries> - <STATUS.fifo_depth>) * <entry size>
. - Write data to fill at most the calculated remaining size.
- Repeat until all data is written.
In case the FIFO runs full (check
STATUS.fifo_full
), software should check the entropy complex is running and can then optionally wait for thefifo_empty
status interrupt before continuing.
In code, this looks something like:
/**
* Absorb input data into the Keccak computation.
*
* Assumes that the KMAC block is in the "absorb" state; it is the caller's
* responsibility to check before calling.
*
* @param in Input buffer.
* @param in_len Length of input buffer (bytes).
* @return Number of bytes written.
*/
size_t kmac_absorb(const uint8_t *in, size_t in_len) {
// Read FIFO depth from the status register.
uint32_t status = abs_mmio_read32(kBase + KMAC_STATUS_REG_OFFSET);
uint32_t fifo_depth =
bitfield_field32_read(status, KMAC_STATUS_FIFO_DEPTH_FIELD);
// Calculate the remaining space in the FIFO using auto-generated KMAC
// parameters and take the minimum of that space and the input length.
size_t free_entries = (KMAC_PARAM_NUM_ENTRIES_MSG_FIFO - fifo_depth);
size_t max_len = free_entries * KMAC_PARAM_NUM_BYTES_MSG_FIFO_ENTRY;
size_t write_len = (in_len < max_len) ? in_len : max_len;
// Note: this example uses byte-writes for simplicity, but in practice it
// would be more efficient to use word-writes for aligned full words and
// byte-writes only as needed at the beginning and end of the input.
for (size_t i = 0; i < write_len; i++) {
abs_mmio_write8(kBase + KMAC_MSG_FIFO_REG_OFFSET, in[i]);
}
return write_len;
}
Note that for modes other than KMAC, i.e., if CFG_SHADOWED.kmac_en
is 0, the KMAC module will not increment the ENTROPY_REFRESH_HASH_CNT
register and thus not trigger automatic reseeds.
It is safe to push to the Message FIFO without checking the STATUS.fifo_depth
register.
Configuring ENTROPY_PERIOD
The ENTROPY_PERIOD
register defines how long the module should wait for entropy during a PRNG reseed before triggering an error.
The configuration value should be carefully chosen based on how the entropy complex is operated.
If CSRNG is running in fully deterministic mode, any EDN request will be answered fairly quickly.
An ENTROPY_PERIOD.wait_timer
value of 5000 in combination with an ENTROPY_PERIOD.prescaler
value of 0 is adequate.
If CSRNG is running in regular, non-deterministic mode, it can happen that the PRNG reseed request of the KMAC module triggers a reseed request from EDN0 to CSRNG.
For Top Earlgrey, producing a single CSRNG seed value is expected to take roughly 5ms.
In the worst case, ENTROPY_SRC must first generate two more seeds to reseed all the other two CSRNG instances.
In this case, the PRNG reseed request of KMAC should get served after roughly 15ms.
If the ENTROPY_SRC is disabled, the interrupt latency and the delay for the startup health testing of the ENTROPY_SRC also need to be factored in to define the ENTROPY_PERIOD
configuration value.
Leaving EDN mode
If the entropy complex becomes unavailable, software can cause the module to leave EDN mode as follows.
Note that for this to work reliably, it is recommended to configure the ENTROPY_PERIOD
register to a non-zero value (see Configuring ENTROPY_PERIOD
).
Otherwise, an already ongoing reseed operation may prevent the following procedure from working.
- Configure the
ENTROPY_PERIOD
to a sufficiently small value such aswait_timer
equals 1 andprescaler
equals 0, or disable EDN0 which interfaces KMAC. - Check that the KMAC module is idle by reading the
STATUS.sha3_idle
bit. - Trigger a PRNG reseed operation via the
CMD.entropy_req
bit. - Wait for the entropy request to timeout and the
kmac_err
interrupt to fire. TheERR_CODE
should now readErrWaitTimerExpired
. - De-assert the
CFG_SHADOWED.entropy_ready
bit. - Set the
CMD.err_processed
bit to signal the processing of the error condition (see also Error Handling).
The FSM controlling the PRNG then goes back into its reset state and software can re-configure the desired mode in the CFG_SHADOWED.entropy_mode
field and set the CFG_SHADOWED.entropy_ready
bit afterwards to latch the configuration.
Error Handling
When the KMAC HW IP encounters an error, it raises the kmac_err
IRQ.
SW can then read the ERR_CODE
CSR to obtain more information about the error.
Having handled that IRQ, SW is expected to clear the kmac_err
bit in the INTR_STATE
CSR before exiting the ISR.
When SW has handled the error condition, it is expected to set the err_processed
bit in the CMD
CSR.
The internal SHA3 engine then flushes its FIFOs and state, which may take a few cycles.
The KMAC HW IP is ready for operation again as soon as the sha3_idle
bit in the STATUS
CSR is set; SW must not change the configuration of or send commands to the KMAC HW IP before that.
If the error occurred while the KMAC HW IP was being used from SW (i.e., not via an HW application interface), the kmac_done
IRQ is raised when the KMAC HW IP is ready again.
KMAC/SHA3 context switching
This version of KMAC/SHA3 HWIP does not support context switching. A context switching scheme would allow software to save the current hashing engine state and initiate a new high priority hashing operation. It could restore the previous hashing state later and continue the operation.