Skip to content

Commit 8ccfa8b

Browse files
h-filalih-filali
committed
[sw,otbn] Add KMAC interface to OTBNsim
Use the new KMAC OTBNsim model to extend OTBNsim. This commit adds new WSRs and CSRs to OTBNsim and connects them to the new KMAC model. Signed-off-by: Hakim Filali <[email protected]>
1 parent e56f509 commit 8ccfa8b

File tree

8 files changed

+530
-17
lines changed

8 files changed

+530
-17
lines changed

‎hw/ip/otbn/README.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -270,6 +270,103 @@ All read-write (RW) CSRs are set to 0 when OTBN starts an operation (when 1 is w
270270
Always reads as 0.
271271
</td>
272272
</tr>
273+
<tr>
274+
<td>0xFC2</td>
275+
<td>RW</td>
276+
<td>KMAC_STATUS</td>
277+
<td>
278+
Writes to this CSR are always ignored.
279+
This CSR exposes the internal state of the SHA3 FSM within KMAC.
280+
<br>
281+
Bit [ 0] SHA3_IDLE indicates whether the SHA3 core is in the idle state.
282+
Bit [ 1] SHA3_ABSORB indicates whether the SHA3 core is in the absorb state.
283+
Bit [ 2] SHA3_SQUEEZE indicates whether the SHA3 core is in the squeeze state.
284+
Bits [31:3] are reserved/ignored.
285+
</td>
286+
</tr>
287+
<tr>
288+
<td>0x7D9</td>
289+
<td>RW</td>
290+
<td>KMAC_IF_STATUS</td>
291+
<td>
292+
Write a 1 to bits 1 or 2 to clear the error bits.
293+
KMAC_IF_STATUS is a CSR that exposes status information for the OTBN-KMAC interface.
294+
<br>
295+
Bit [ 0] MSG_WRITE_RDY indicates whether the KMAC_DATA_S0/1 WSR is ready for the next word.
296+
Bit [ 1] MSG_SEND_ERROR indicates whether an error ocurred after issuing a message send command.
297+
Bit [ 2] MSG_WRITE_ERROR indicates whether an error ocurred after writing to the KMAC_DATA_S0/1 WSR.
298+
Bit [ 3] DIGEST_VALID0 indicates whether word 0 in the KMAC_DATA_S0/1 WSR is valid.
299+
Bit [ 4] DIGEST_VALID1 indicates whether word 1 in the KMAC_DATA_S0/1 WSR is valid.
300+
Bit [ 5] DIGEST_VALID2 indicates whether word 2 in the KMAC_DATA_S0/1 WSR is valid.
301+
Bit [ 6] DIGEST_VALID3 indicates whether word 3 in the KMAC_DATA_S0/1 WSR is valid.
302+
Bits [31:7] are reserved/ignored.
303+
</td>
304+
</tr>
305+
<tr>
306+
<td>0x7DA</td>
307+
<td>RW</td>
308+
<td>KMAC_INTR</td>
309+
<td>
310+
Writing 1 to bit 0 of this register clears the interrupt.
311+
KMAC_INTR is a CSR that exposes a KMAC_ERROR interrupt of the KMAC HW IP.
312+
<br>
313+
Bit [ 0] KMAC_ERROR indicates whether an error ocurred in the KMAC HW IP.
314+
Bits [31:1] are reserved/ignored.
315+
</td>
316+
</tr>
317+
<tr>
318+
<td>0xFC3</td>
319+
<td>RW</td>
320+
<td>KMAC_ERROR</td>
321+
<td>
322+
Writes to this register are ignored.
323+
This register exposes information from the KMAC HW IP ERR_CODE register.
324+
</td>
325+
</tr>
326+
<tr>
327+
<td>0x7DB</td>
328+
<td>RW</td>
329+
<td>KMAC_CFG</td>
330+
<td>
331+
This register allows OTBN to set the KMAC hashing mode (mode = SHAKE / cSHAKE / SHA3), enable or disable keyed KMAC mode (kmac_en = 0/1), and select the desired security strength (kstrength = L128 / L224 / L256 / L384 / L512).
332+
Reading from this register returns the current KMAC configuration.
333+
<br>
334+
Bit [ 0] KMAC_EN enables keyed operation in the KMAC HWIP.
335+
Bits [ 3:1] STRENGTH is the KAMC security strength.
336+
Bits [ 5:4] MODE is the KMAC hashing mode.
337+
Bits [31:6] are reserved/ignored.
338+
</td>
339+
</tr>
340+
<tr>
341+
<td>0x7DC</td>
342+
<td>RW</td>
343+
<td>KMAC_MSG_SEND</td>
344+
<td>
345+
This CSR consists of a single bit that, if set to one, will trigger OTBN to send the contents of KMAC_DATA_S0 and KMAC_DATA_S1 to KMAC.
346+
Reads from this register always return a 0.
347+
</td>
348+
</tr>
349+
<tr>
350+
<td>0x7DD</td>
351+
<td>RW</td>
352+
<td>KMAC_CMD</td>
353+
<td>
354+
The register allows OTBN to issue START, PROCESS, RUN and DONE commands to KMAC.
355+
Reads from this register always return a 0.
356+
<br>
357+
Bit [ 5:0] CMD is the KMAC command field.
358+
Bits [31:6] are reserved/ignored.
359+
</td>
360+
</tr>
361+
<tr>
362+
<td>0x7DE</td>
363+
<td>RW</td>
364+
<td>KMAC_BYTE_STROBE</td>
365+
<td>
366+
BYTE_STROBE is a CSR that specifies which input bytes of KMAC_DATA_S0/1 are valid and should be consumed by KMAC.
367+
Reads from this register return the current configuration of the KMAC_BYTE_STROBE CSR.
368+
</td>
369+
</tr>
273370
<tr>
274371
<td>0xFC0</td>
275372
<td>RO</td>
@@ -422,6 +519,24 @@ All read-write (RW) WSRs are set to 0 when OTBN starts an operation (when 1 is w
422519
A `KEY_INVALID` software error is raised on read if the Key Manager has not provided a valid key.
423520
</td>
424521
</tr>
522+
<tr>
523+
<td>0x8</td>
524+
<td>RW</td>
525+
<td><a name="kmac-data-s0">KMAC_DATA_S0</a></td>
526+
<td>
527+
KMAC_DATA_S0 is used by OTBN to provide masked input message shares to KMAC and to retrieve masked digest shares.
528+
This WSR is 256 bits wide and holds one share of the message or digest.
529+
</td>
530+
</tr>
531+
<tr>
532+
<td>0x9</td>
533+
<td>RW</td>
534+
<td><a name="kmac-data-s1">KMAC_DATA_S1</a></td>
535+
<td>
536+
KMAC_DATA_S1 is used by OTBN to provide masked input message shares to KMAC and to retrieve masked digest shares.
537+
This WSR is 256 bits wide and holds one share of the message or digest.
538+
</td>
539+
</tr>
425540
</tbody>
426541
</table>
427542

‎hw/ip/otbn/data/csr.yml‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,79 @@
9696
Write to this CSR to begin a request to fill the RND cache.
9797
Always reads as 0.
9898
99+
- name: kmac_status
100+
address: 0xfc2
101+
doc: |
102+
Writes to this CSR are always ignored.
103+
This CSR exposes the internal state of the SHA3 FSM within KMAC.
104+
105+
Bit [ 0] SHA3_IDLE indicates whether the SHA3 core is in the idle state.
106+
Bit [ 1] SHA3_ABSORB indicates whether the SHA3 core is in the absorb state.
107+
Bit [ 2] SHA3_SQUEEZE indicates whether the SHA3 core is in the squeeze state.
108+
Bits [31:3] are reserved/ignored.
109+
110+
- name: kmac_if_status
111+
address: 0x7d9
112+
doc: |
113+
Write a 1 to bits 1 or 2 to clear the error bits.
114+
KMAC_IF_STATUS is a CSR that exposes status information for the OTBN-KMAC interface.
115+
116+
Bit [ 0] MSG_WRITE_RDY indicates whether the KMAC_DATA_S0/1 WSR is ready for the next word.
117+
Bit [ 1] MSG_SEND_ERROR indicates whether an error ocurred after issuing a message send command.
118+
Bit [ 2] MSG_WRITE_ERROR indicates whether an error ocurred after writing to the KMAC_DATA_S0/1 WSR.
119+
Bit [ 3] DIGEST_VALID0 indicates whether word 0 in the KMAC_DATA_S0/1 WSR is valid.
120+
Bit [ 4] DIGEST_VALID1 indicates whether word 1 in the KMAC_DATA_S0/1 WSR is valid.
121+
Bit [ 5] DIGEST_VALID2 indicates whether word 2 in the KMAC_DATA_S0/1 WSR is valid.
122+
Bit [ 6] DIGEST_VALID3 indicates whether word 3 in the KMAC_DATA_S0/1 WSR is valid.
123+
Bits [31:7] are reserved/ignored.
124+
125+
- name: kmac_intr
126+
address: 0x7da
127+
doc: |
128+
Writing 1 to bit 0 of this register clears the interrupt.
129+
KMAC_INTR is a CSR that exposes a KMAC_ERROR interrupt of the KMAC HW IP.
130+
131+
Bit [ 0] KMAC_ERROR indicates whether an error ocurred in the KMAC HW IP.
132+
Bits [31:1] are reserved/ignored.
133+
134+
- name: kmac_error
135+
address: 0xfc3
136+
doc: |
137+
Writes to this register are ignored.
138+
This register exposes information from the KMAC HW IP ERR_CODE register.
139+
140+
- name: kmac_cfg
141+
address: 0x7db
142+
doc: |
143+
This register allows OTBN to set the KMAC hashing mode (mode = SHAKE / cSHAKE / SHA3), enable or disable keyed KMAC mode (kmac_en = 0/1), and select the desired security strength (kstrength = L128 / L224 / L256 / L384 / L512).
144+
Reading from this register returns the current KMAC configuration.
145+
146+
Bit [ 0] KMAC_EN enables keyed operation in the KMAC HWIP.
147+
Bits [ 3:1] STRENGTH is the KAMC security strength.
148+
Bits [ 5:4] MODE is the KMAC hashing mode.
149+
Bits [31:6] are reserved/ignored.
150+
151+
- name: kmac_msg_send
152+
address: 0x7dc
153+
doc: |
154+
This CSR consists of a single bit that, if set to one, will trigger OTBN to send the contents of KMAC_DATA_S0 and KMAC_DATA_S1 to KMAC.
155+
Reads from this register always return a 0.
156+
157+
- name: kmac_cmd
158+
address: 0x7dd
159+
doc: |
160+
The register allows OTBN to issue START, PROCESS, RUN and DONE commands to KMAC.
161+
Reads from this register always return a 0.
162+
163+
Bit [ 5:0] CMD is the KMAC command field.
164+
Bits [31:6] are reserved/ignored.
165+
166+
- name: kmac_byte_strobe
167+
address: 0x7de
168+
doc: |
169+
BYTE_STROBE is a CSR that specifies which input bytes of KMAC_DATA_S0/1 are valid and should be consumed by KMAC.
170+
Reads from this register return the current configuration of the KMAC_BYTE_STROBE CSR.
171+
99172
- name: rnd
100173
address: 0xfc0
101174
read-only: true

‎hw/ip/otbn/data/wsr.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,15 @@
6767
Bits [127:0] contain bits [383:256] of share 1 of the 384b OTBN sideload key provided by the [Key Manager](../keymgr/README.md).
6868
6969
A `KEY_INVALID` software error is raised on read if the Key Manager has not provided a valid key.
70+
71+
- name: kmac_data_s0
72+
address: 8
73+
doc: |
74+
KMAC_DATA_S0 is used by OTBN to provide masked input message shares to KMAC and to retrieve masked digest shares.
75+
This WSR is 256 bits wide and holds one share of the message or digest.
76+
77+
- name: kmac_data_s1
78+
address: 9
79+
doc: |
80+
KMAC_DATA_S1 is used by OTBN to provide masked input message shares to KMAC and to retrieve masked digest shares.
81+
This WSR is 256 bits wide and holds one share of the message or digest.

‎hw/ip/otbn/dv/otbnsim/sim/BUILD‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ py_library(
1717
srcs = ["csr.py"],
1818
deps = [
1919
":flags",
20+
":kmac",
2021
":wsr",
2122
],
2223
)
@@ -163,6 +164,7 @@ py_library(
163164
":ext_regs",
164165
":flags",
165166
":gpr",
167+
":kmac",
166168
":loop",
167169
":reg",
168170
":trace",
@@ -193,6 +195,7 @@ py_library(
193195
srcs = ["wsr.py"],
194196
deps = [
195197
":ext_regs",
198+
":kmac",
196199
":trace",
197200
],
198201
)

0 commit comments

Comments
 (0)