Hardware Interfaces

Referring to the Comportable guideline for peripheral device functionality, the module hmac has the following hardware interfaces defined

  • Primary Clock: clk_i
  • Other Clocks: none
  • Bus Device Interfaces (TL-UL): tl
  • Bus Host Interfaces (TL-UL): none
  • Peripheral Pins for Chip IO: none

Inter-Module Signals

Port NamePackage::StructTypeActWidthDescription
idleprim_mubi_pkg::mubi4unireq1
tltlul_pkg::tlreq_rsprsp1

Interrupts

Interrupt NameTypeDescription
hmac_doneEventHMAC-256 completes a message with key
fifo_emptyEventMessage FIFO empty condition
hmac_errEventHMAC error occurred. ERR_CODE register shows which error occurred

Security Alerts

Alert NameDescription
fatal_faultThis fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.

Security Countermeasures

Countermeasure IDDescription
HMAC.BUS.INTEGRITYEnd-to-end bus integrity scheme.

Registers

Summary

NameOffsetLengthDescription
hmac.INTR_STATE0x04Interrupt State Register
hmac.INTR_ENABLE0x44Interrupt Enable Register
hmac.INTR_TEST0x84Interrupt Test Register
hmac.ALERT_TEST0xc4Alert Test Register
hmac.CFG0x104HMAC Configuration register.
hmac.CMD0x144HMAC command register
hmac.STATUS0x184HMAC Status register
hmac.ERR_CODE0x1c4HMAC Error Code
hmac.WIPE_SECRET0x204Randomize internal secret registers.
hmac.KEY_00x244HMAC Secret Key
hmac.KEY_10x284HMAC Secret Key
hmac.KEY_20x2c4HMAC Secret Key
hmac.KEY_30x304HMAC Secret Key
hmac.KEY_40x344HMAC Secret Key
hmac.KEY_50x384HMAC Secret Key
hmac.KEY_60x3c4HMAC Secret Key
hmac.KEY_70x404HMAC Secret Key
hmac.DIGEST_00x444Digest output. If HMAC is disabled, the register shows result of SHA256
hmac.DIGEST_10x484Digest output. If HMAC is disabled, the register shows result of SHA256
hmac.DIGEST_20x4c4Digest output. If HMAC is disabled, the register shows result of SHA256
hmac.DIGEST_30x504Digest output. If HMAC is disabled, the register shows result of SHA256
hmac.DIGEST_40x544Digest output. If HMAC is disabled, the register shows result of SHA256
hmac.DIGEST_50x584Digest output. If HMAC is disabled, the register shows result of SHA256
hmac.DIGEST_60x5c4Digest output. If HMAC is disabled, the register shows result of SHA256
hmac.DIGEST_70x604Digest output. If HMAC is disabled, the register shows result of SHA256
hmac.MSG_LENGTH_LOWER0x644Received Message Length calculated by the HMAC in bits [31:0]
hmac.MSG_LENGTH_UPPER0x684Received Message Length calculated by the HMAC in bits [63:32]
hmac.MSG_FIFO0x8002048Message 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)

INTR_STATE

Interrupt State Register

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

Fields

BitsTypeResetNameDescription
31:3Reserved
2rw1c0x0hmac_errHMAC error occurred. ERR_CODE register shows which error occurred
1rw1c0x0fifo_emptyMessage FIFO empty condition
0rw1c0x0hmac_doneHMAC-256 completes a message with key

INTR_ENABLE

Interrupt Enable Register

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

Fields

BitsTypeResetNameDescription
31:3Reserved
2rw0x0hmac_errEnable interrupt when INTR_STATE.hmac_err is set.
1rw0x0fifo_emptyEnable interrupt when INTR_STATE.fifo_empty is set.
0rw0x0hmac_doneEnable interrupt when INTR_STATE.hmac_done is set.

INTR_TEST

Interrupt Test Register

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

Fields

BitsTypeResetNameDescription
31:3Reserved
2wo0x0hmac_errWrite 1 to force INTR_STATE.hmac_err to 1.
1wo0x0fifo_emptyWrite 1 to force INTR_STATE.fifo_empty to 1.
0wo0x0hmac_doneWrite 1 to force INTR_STATE.hmac_done to 1.

ALERT_TEST

Alert Test Register

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

Fields

BitsTypeResetNameDescription
31:1Reserved
0wo0x0fatal_faultWrite 1 to trigger one alert event of this kind.

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: 0x0
  • Reset mask: 0xf

Fields

BitsTypeResetName
31:4Reserved
3rw0x0digest_swap
2rw0x0endian_swap
1rwxsha_en
0rwxhmac_en

CFG . digest_swap

Digest register byte swap.

If 1 the value contained 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

SHA256 enable. If 0, SHA engine won’t initiate compression, this is used to stop operation of the SHA engine until configuration has been done. When the SHA 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: 0x3

Fields

BitsTypeResetNameDescription
31:2Reserved
1r0w1cxhash_processIf writes 1 into this field, SHA256 or HMAC calculates the digest or signing based on currently received message.
0r0w1cxhash_startIf writes 1 into this field, SHA256 or HMAC begins its operation. CPU should configure relative information first, such as message_length, secret_key.

STATUS

HMAC Status register

  • Offset: 0x18
  • Reset default: 0x1
  • Reset mask: 0x1f3

Fields

BitsTypeResetNameDescription
31:9Reserved
8:4roxfifo_depthFIFO entry count.
3:2Reserved
1roxfifo_fullFIFO full. Data written to the FIFO whilst it is full will cause back-pressure on the interconnect
0ro0x1fifo_emptyFIFO empty

ERR_CODE

HMAC Error Code

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

Fields

BitsTypeResetNameDescription
31:0ro0x0err_codeIf error interrupt occurs, this register has information of error cause. Please take a look at `hw/ip/hmac/rtl/hmac_pkg.sv:err_code_e enum type.

WIPE_SECRET

Randomize internal secret registers.

If CPU writes value into the register, the value is used to randomize internal variables such as secret key, internal state machine, or hash value.

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

Fields

BitsTypeResetNameDescription
31:0woxsecretSecret value

KEY

HMAC Secret Key

SHA256 assumes secret key is hashed 256bit key. Order of the secret key is: key[255:0] = {KEY0, KEY1, KEY2, … , KEY7};

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

NameOffset
KEY_00x24
KEY_10x28
KEY_20x2c
KEY_30x30
KEY_40x34
KEY_50x38
KEY_60x3c
KEY_70x40

Fields

BitsTypeResetNameDescription
31:0woxkey32-bit chunk of 256-bit Secret Key

DIGEST

Digest output. If HMAC is disabled, the register shows result of SHA256

Order of the digest is: digest[255:0] = {DIGEST0, DIGEST1, DIGEST2, … , DIGEST7};

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

Instances

NameOffset
DIGEST_00x44
DIGEST_10x48
DIGEST_20x4c
DIGEST_30x50
DIGEST_40x54
DIGEST_50x58
DIGEST_60x5c
DIGEST_70x60

Fields

BitsTypeResetNameDescription
31:0roxdigest32-bit chunk of 256-bit Digest

MSG_LENGTH_LOWER

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

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

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

Fields

BitsTypeResetNameDescription
31:0ro0x0vMessage Length [31:0]

MSG_LENGTH_UPPER

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

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

Fields

BitsTypeResetNameDescription
31:0ro0x0vMessage Length [63:32]

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: 0x800to0xffc
  • Size (words): 512
  • Access: wo
  • Byte writes are supported.