Registers

Summary

INTR_STATE

Interrupt State Register

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

Fields

{"reg": [{"name": "hmac_done", "bits": 1, "attr": ["rw1c"], "rotate": -90}, {"name": "fifo_empty", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "hmac_err", "bits": 1, "attr": ["rw1c"], "rotate": -90}, {"bits": 29}], "config": {"lanes": 1, "fontsize": 10, "vspace": 120}}

INTR_STATE . hmac_err

HMAC error has occurred. ERR_CODE register shows which error occurred.

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 HMAC block is not running in HMAC mode and performing the second round of computing the final hash of the outer key as well as the result of the first round using the inner key. ii) Software has not yet written the Process or Stop command to finish the hashing operation. 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 . hmac_done

HMAC/SHA-2 has completed.

INTR_ENABLE

Interrupt Enable Register

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

Fields

{"reg": [{"name": "hmac_done", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "fifo_empty", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "hmac_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": "hmac_done", "bits": 1, "attr": ["wo"], "rotate": -90}, {"name": "fifo_empty", "bits": 1, "attr": ["wo"], "rotate": -90}, {"name": "hmac_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: 0x1

Fields

{"reg": [{"name": "fatal_fault", "bits": 1, "attr": ["wo"], "rotate": -90}, {"bits": 31}], "config": {"lanes": 1, "fontsize": 10, "vspace": 130}}

CFG

HMAC Configuration register.

The register is updated when the engine is in Idle. If the software updates the register while the engine computes the hash, the updated value is discarded.

• Offset: 0x10
• Reset default: 0x4100
• Reset mask: 0x7fff

Fields

{"reg": [{"name": "hmac_en", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "sha_en", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "endian_swap", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "digest_swap", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "key_swap", "bits": 1, "attr": ["rw"], "rotate": -90}, {"name": "digest_size", "bits": 4, "attr": ["rw"], "rotate": -90}, {"name": "key_length", "bits": 6, "attr": ["rw"], "rotate": 0}, {"bits": 17}], "config": {"lanes": 1, "fontsize": 10, "vspace": 130}}

CFG . key_length

Key length configuration.

This is a 6-bit one-hot encoded field to configure the key length for HMAC.

The HMAC can be programmed with the following key lengths: 128-bit, 256-bit, 384-bit, 512-bit and 1024-bit. But the HMAC supports any arbitrary key length: the software should configure the HMAC with the next largest supported key length and concatenate zeros to reach the programmed key length. The position of these zeros depends on the endianness, thus on the programmed CFG.key_swap. For example, for an 80-bit key, HMAC should be configured with an 128-bit key length, fed with the 80-bit key and with 48 zero-bits.

Note that the key length cannot be greater than the block size: up to 1024-bit for SHA-2 384/512 and up to 512-bit for SHA-2 256. The value of this register is irrelevant when only SHA-2 (not keyed HMAC) is configured. However, for HMAC mode (hmac_en == 1), when HMAC is triggered to start while KEY_LENGTH holds Key_None or KEY_LENGTH holds Key_1024 for DIGEST_SIZE = SHA2_256, starting is blocked and an error is signalled to SW.

Other values are reserved.

CFG . digest_size

Digest size configuration.

This is a 4-bit one-hot encoded field to select digest size for either HMAC or SHA-2. Invalid/unsupported values, i.e., values that don’t correspond to SHA2_256, SHA2_384, or SHA2_512, are mapped to SHA2_None.

Other values are reserved.

CFG . key_swap

Key register byte swap.

If 1 the endianness of each KEY_* register is swapped. Default value (value 0) is big endian representation of the KEY_* CSRs.

CFG . digest_swap

Digest register byte swap.

If 1 the value in each digest output register is converted to big-endian byte order. This setting does not affect the order of the digest output registers, DIGEST_0 still contains the first 4 bytes of the digest.

CFG . endian_swap

Endian swap.

If 0, each value will be added to the message in little-endian byte order. The value is written to MSG_FIFO same to the SW writes. 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. 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 . sha_en

SHA-2 enable.

If 0, the SHA engine will not initiate compression, this is used to stop operation of the SHA-2 engine until configuration has been done. When the SHA-2 engine is disabled the digest is cleared.

CFG . hmac_en

HMAC datapath enable.

If this bit is 1, HMAC operates when hash_start toggles.

CMD

HMAC command register

• Offset: 0x14
• Reset default: 0x0
• Reset mask: 0xf

Fields

{"reg": [{"name": "hash_start", "bits": 1, "attr": ["r0w1c"], "rotate": -90}, {"name": "hash_process", "bits": 1, "attr": ["r0w1c"], "rotate": -90}, {"name": "hash_stop", "bits": 1, "attr": ["r0w1c"], "rotate": -90}, {"name": "hash_continue", "bits": 1, "attr": ["r0w1c"], "rotate": -90}, {"bits": 28}], "config": {"lanes": 1, "fontsize": 10, "vspace": 150}}

CMD . hash_continue

When 1 is written to this field, SHA-2 or HMAC will continue hashing based on the current hash in the digest registers and the message length, which both have to be restored to switch context.

CMD . hash_stop

When 1 is written to this field, SHA-2 or HMAC will afterwards set the hmac_done interrupt as soon as the current block has been hashed. The hash can then be read from the registers DIGEST_0 to DIGEST_15. Together with the message length in MSG_LENGTH_LOWER and MSG_LENGTH_UPPER, this forms the information that has to be saved before switching context.

CMD . hash_process

If 1 is written to this field, SHA-2 or HMAC calculates the digest or signing based on currently received message.

CMD . hash_start

If 1 is written into this field, SHA-2 or HMAC begins its operation. CPU must configure relative information first, such as the digest size, secret key and the key length.

STATUS

HMAC Status register

• Offset: 0x18
• Reset default: 0x3
• Reset mask: 0x3f7

Fields

{"reg": [{"name": "hmac_idle", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "fifo_empty", "bits": 1, "attr": ["ro"], "rotate": -90}, {"name": "fifo_full", "bits": 1, "attr": ["ro"], "rotate": -90}, {"bits": 1}, {"name": "fifo_depth", "bits": 6, "attr": ["ro"], "rotate": 0}, {"bits": 22}], "config": {"lanes": 1, "fontsize": 10, "vspace": 120}}

ERR_CODE

HMAC Error Code

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

Fields

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

WIPE_SECRET

Clear internal secret registers.

If CPU writes a value into the register, the value is used to clear the internal variables such as the secret key, internal state machine, or hash value. The clear secret operation overwrites the internal variables with the provided 32-bit value. For SHA-2 384/512 that work with 64-bit words, the 32-bit value is duplicated and concatenated to generate the 64-bit value. It is recommended to use a value extracted from an entropy source.

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

Fields

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

KEY

HMAC Secret Key

HMAC using SHA-2 256/384/512 assumes any hashed secret key length up to the block size, thus capped at 1024-bit. key_length determines how many of these registers are relevant for the HMAC operation. Order of the secret key is: key[1023:0] = {KEY0, KEY1, KEY2, … , KEY31};

The registers are allowed to be updated only 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": "key", "bits": 32, "attr": ["wo"], "rotate": 0}], "config": {"lanes": 1, "fontsize": 10, "vspace": 80}}

DIGEST

Digest output.

If HMAC is disabled, the register shows result of SHA-2 256/384/512. Order of the 512-bit digest[511:0] = {DIGEST0, DIGEST1, DIGEST2, … , DIGEST15}. For SHA-2 256 order of the 256-bit digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, DIGEST3, DIGEST4, DIGEST5, DIGEST6, DIGEST7} and {DIGEST8 - DIGEST15} are irrelevant and should not be read out. For SHA-2 384, {DIGEST12-DIGEST15} are truncated; they are irrelevant and should not be read out.

The digest gets cleared when CFG.sha_en transitions from 1 to 0. When STATUS.hmac_idle is 1, these registers may be written to by software. Outside of this window, writes can cause unpredictable behavior.

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

Instances

Fields

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

MSG_LENGTH_LOWER

Received Message Length calculated by the HMAC in bits [31:0]

Message is byte granularity. Lower 3 bits [2:0] are ignored.

When STATUS.hmac_idle is 1, this register may be written by software. Outside of this window, writes can cause unpredictable behavior.

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

Fields

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

MSG_LENGTH_UPPER

Received Message Length calculated by the HMAC in bits [63:32]

When STATUS.hmac_idle is 1, this register may be written by software. Outside of this window, writes can cause unpredictable behavior. For SHA-2-2 256 computations, message length is 64-bit {MSG_LENGTH_UPPER, MSG_LENGTH_LOWER}.f For SHA-2 384/512 message length is extended to 128-bit in line with [nist-fips-180-4] where the upper 64 bits get zero-padded: {32’b0, 32’b0, MSG_LENGTH_UPPER, MSG_LENGTH_LOWER}.

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

Fields

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

MSG_FIFO

Message FIFO. Any write to this window will be appended to the FIFO. Only the lower [1:0] bits of the address matter to writes within the window (for correctly dealing with non 32-bit writes)

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