sep_abr_kv_shim

Present Adams Bridge Caliptra Key-Vault ports from the ABR sideload CSR hardware interface.

SEP has no Caliptra KV; the Key Manager pushes keys into abr_wrapper_key_reg over a private 32-bit AXI4-Lite bus. This shim consumes that decoded hwif and re-presents Caliptra kv_read / kv_rd_resp / kv_write / kv_wr_resp.

Seeds are stored as dual XOR shares; plaintext dword i is SHARE0[i] ^ SHARE1[i], and a read reports error while the entry's key_valid is clear. The seed is write-only in the CSR and never reconstructed outside this shim, so abr_top's mldsa_privkey_lock stays engaged.

abr_ctrl stores KV read offset k in register index N-1-k of each N-dword block, and presents shared-key word N-1-k at KV write offset k. Each lane therefore serves KV offset k from Key Manager word N-1-k of the addressed block, and the write path stores offset k in KEY[N-1-k], so Key Manager word i and ABR register index i carry the same dword in both directions.

kv_read is combinational with respect to read_offset: AB's kv_read_client samples kv_rd_resp.read_data in the same cycle. The client ends on (offset == num_dwords-1) or kv_rd_resp.last; kv_rd_resp.error latches KV_READ_FAIL. The kv_read ports carry:

  • kv_read[0]: the ML-DSA seed (256b / 8 dwords).
  • kv_read[1]: the ML-KEM seed D||Z (512b / 16 dwords: offsets 0..7 stream seed_D, 8..15 stream seed_Z); succeeds only when both D and Z are valid.
  • kv_read[2]: the ML-KEM msg (256b / 8 dwords).

kv_write writes ML-KEM shared-key dwords into MLKEM_SHARED_KEY via hwif_o and, on the final dword, pulses KEY_CTRL.key_valid.hwset and IRQ_STATUS.key_valid.hwset. kv_wr_resp is acknowledged with no error.

Parameters

Table 1. Parameters
NameTypeDefaultDescription
SEED_DWORDSint unsigned8Dwords per seed block (ML-DSA-87 seed, ML-KEM seed D or Z); 8 dwords = 256 bits.
MSG_DWORDSint unsigned8Dwords in the ML-KEM message; 8 dwords = 256 bits.
SHARED_KEY_DWORDSint unsigned8Dwords in the ML-KEM shared key; 8 dwords = 256 bits.

Ports

Table 2. Ports
NameDirectionTypeDescription
hwif_iinputabr_wrapper_key__out_tABR sideload CSR hardware outputs: Key Manager-written seed and message shares and their key_valid bits.
hwif_ooutputabr_wrapper_key__in_tABR sideload CSR hardware inputs for ML-KEM shared-key writeback and its key_valid and IRQ_STATUS set pulses.
kv_read_iinputkv_read_t [2:0]Adams Bridge Caliptra KV read commands: lane 0 ML-DSA seed, lane 1 ML-KEM seed D||Z, lane 2 ML-KEM message.
kv_rd_resp_ooutputkv_rd_resp_t [2:0]KV read responses, combinational in read_offset; last on the final dword and error while the entry is not valid.
kv_write_iinputkv_write_tAdams Bridge Caliptra KV write command for the ML-KEM shared key.
kv_wr_resp_ooutputkv_wr_resp_tAdams Bridge Caliptra KV write response; acknowledged with no error.