blob: f1c92a80732e799336dd9c225bf0be4e92557688 [file] [log] [blame]
Udi Jonnalagadda95bcc902020-10-29 16:24:34 -07001// Copyright lowRISC contributors.
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4{
Udi Jonnalagadda308ca992021-06-02 10:38:09 -07005 name: kmac
Udi Jonnalagadda95bcc902020-10-29 16:24:34 -07006 import_testplans: ["hw/dv/tools/dvsim/testplans/csr_testplan.hjson",
7 "hw/dv/tools/dvsim/testplans/intr_test_testplan.hjson",
Udi Jonnalagadda47690072021-03-15 16:07:06 -07008 "hw/dv/tools/dvsim/testplans/mem_testplan.hjson",
Udi Jonnalagadda0b620082021-08-18 12:34:27 -07009 "hw/dv/tools/dvsim/testplans/alert_test_testplan.hjson",
Cindy Chen793f6232022-02-01 14:00:02 -080010 "hw/dv/tools/dvsim/testplans/shadow_reg_errors_testplan.hjson",
Udi Jonnalagadda8eab1172021-06-01 17:32:48 -070011 "hw/dv/tools/dvsim/testplans/stress_all_with_reset_testplan.hjson",
Srikrishna Iyera463e172022-02-02 12:09:39 -080012 "hw/dv/tools/dvsim/testplans/tl_device_access_types_testplan.hjson",
13 "kmac_sec_cm_testplan.hjson"]
Srikrishna Iyer86169d02021-05-10 09:35:52 -070014 testpoints: [
Udi Jonnalagadda95bcc902020-10-29 16:24:34 -070015 {
Cindy Chena53bfc02020-11-11 10:15:34 -080016 name: smoke
Udi Jonnalagadda95bcc902020-10-29 16:24:34 -070017 desc: '''
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080018 KMAC smoke test will contain a number of rounds, and acts as a base for many other tests.
19 In each round, we run a full KMAC hashing operation:
20 - Randomly enable interrupts, operation mode (SHA3/SHAKE/CSHAKE/KMAC), key length (if
21 applicable), constraining all settings to be legal.
22 - Set function name to "KMAC" and set customization string as empty if applicable.
23 - Randomly set endianness of input msg and internal keccak state.
24 - Randomly provide a sideloaded key, do not set cfg.sideload.
Udi Jonnalagadda5cde4b82020-12-23 14:07:45 -080025 - Set output length between 1-`keccak_rate` bytes if applicable.
Udi Jonnalagadda0834b192021-05-03 17:39:08 -070026 - Randomly select either SW or EDN as the source of entropy
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080027 - Trigger KMAC to start absorbing input message.
28 - During absorption stage randomly read from STATE window, expect 0.
29 - Write message to MSG_FIFO window, maximum length of 32 bytes.
30 - Check SHA3 engine status.
31 - Trigger KMAC to finish absorbing stage, check kmac_done is set and status.squeeze is
32 set.
33 - Read output digest, and compare against output from reference C++ model.
34 - In masked configuration: both shares are XORed to get unmasked result digest.
35 - In unmasked configuration: Share1 is the result digest, Share2 should be 0.
36 - Signal cmd.done to tell KMAC to clear internal state.
37 - Try reading output digest again, confirm that it is 0.
Udi Jonnalagaddaf1d09532021-05-17 10:53:19 -070038
39 This test, and all other tests in the testplan, will be checked for correctness
40 in two different ways:
41 - first, a DPI-C model is used to check that the correct digest value is produced
42 - a cycle-accurate model is implemented in the scoreboard to provide constant checks
43 during each hash operation and ensure that internal state is being updated
44 correctly
Udi Jonnalagadda95bcc902020-10-29 16:24:34 -070045 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -070046 stage: V1
Weicai Yanga1afa1d2022-12-16 16:20:16 -080047 tests: ["{name}_smoke"]
Udi Jonnalagadda95bcc902020-10-29 16:24:34 -070048 }
49 {
Udi Jonnalagaddadad81782021-02-08 16:02:28 -080050 name: long_msg_and_output
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080051 desc: '''
52 Same as the smoke test, except with a message of up to 100KB.
53 Max firmware input size for KMAX is around 392KB, but this is too large for a DV
54 simulation.
55 Average input size from firmware would be around 60-100KB, so we use 100KB as a max
56 input size for DV, but will enable easy extensibility for emulation testing where we can
57 enable much larger messages.
58 Allow output length to vary up to 1KB (for XOF functions).
Udi Jonnalagadda5cde4b82020-12-23 14:07:45 -080059 If output length is greater than `keccak_rate` bytes, keccak rounds will be run manually to
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080060 squeeze extra output data.
61 Set function name as "KMAC" and enable full randomization of customization string (if
62 applicable).
63 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -070064 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -080065 tests: ["{name}_long_msg_and_output"]
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080066 }
67 {
Udi Jonnalagadda5bc27bd2021-02-12 10:59:47 -080068 name: burst_write
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080069 desc: '''
70 This is the same as the long_message test, except we burst-write chunks of the message
71 into the msg_fifo, and disable intermediate status/CSR checks.
72 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -070073 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -080074 tests: ["{name}_burst_write"]
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080075 }
76 {
77 name: test_vectors
78 desc: '''
79 These tests drive NIST test vectors for SHA3/SHAKE/KMAC into the design and check
80 the output against the expected digest values.
81 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -070082 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -080083 tests: ["{name}_test_vectors_sha3_224", "{name}_test_vectors_sha3_256",
84 "{name}_test_vectors_sha3_384", "{name}_test_vectors_sha3_512",
85 "{name}_test_vectors_shake_128", "{name}_test_vectors_shake_256",
86 "{name}_test_vectors_kmac", "{name}_test_vectors_kmac_xof"]
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080087 }
88 {
89 name: sideload
90 desc: '''
Udi Jonnalagaddae8252d42021-02-08 18:30:58 -080091 Same as the smoke test, except we set cfg.sideload and provide a
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080092 valid sideloaded key as well as a valid SW-provided key.
Cindy Chene9e192a2022-07-14 16:16:39 -070093 KMAC should operate on the sideloaded key regardless of the cfg_shadowed.sideload field
94 value.
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080095 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -070096 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -080097 tests: ["{name}_sideload"]
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -080098 }
99 {
Udi Jonnalagadda556dd652021-04-29 14:25:20 -0700100 name: app
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -0800101 desc: '''
Michael Schaffnere2a5d482021-05-19 13:22:23 -0700102 Test that the Keymgr/ROM/LC can all initiate a KMAC operation through
103 the application interface - Keymgr uses KMAC hash, while ROM/LC use CShake.
Udi Jonnalagadda556dd652021-04-29 14:25:20 -0700104 Use an array of kmac_app_agents to send message data to the KMAC and to control
105 the hashing logic, and set cfg.sideload if the Keymgr is enabled.
106 The result digest sent to the kmac_app_agent will be compared against the result from
107 the DPI reference model.
108 In addition, read from the STATE window afterwards and confirm that this access is
109 blocked and will return 0.
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -0800110 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -0700111 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800112 tests: ["{name}_app"]
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -0800113 }
114 {
Cindy Chenf542b1d2022-02-18 10:56:22 -0800115 name: app_with_partial_data
116 desc: '''
117 Basd on the kmac_app test, this test will send partial data from application interface
118 by sending `strb` with values other than `8'hFF`.
119 Because the scoreboard is cycle accurate and does not support this feature, this test
120 will not check `status` and `intr_state` registers, but will check other registers and
121 all interface data including digest.
122 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -0700123 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800124 tests: ["{name}_app_with_partial_data"]
Cindy Chenf542b1d2022-02-18 10:56:22 -0800125 }
126 {
Cindy Cheneb071dc2022-09-13 12:30:19 -0700127 name: entropy_refresh
128 desc: ''' Test entropy interface for KMAC.
129
130 This test randomly chooses to execute either a SW-controlled hash or a hash from the
131 App interface.
132 All configuration fields are left as is, but now we will request EDN entropy by setting
133 the following registers with random value:
134 - "cmd.entropy_req": Request an EDN entropy
135 - "cmd.hash_cnt_clear": Clear the entropy_refresh_hash_cnt
136 - "entropy_refresh_threshold_shadowed": The threshold when KMAC should request an EDN
137 entropy
138
139 In masked mode, scoreboard will check:
140 - Register `entropy_refresh_hash_cnt` value
141 - KMAC requests EDN at the correct time
142
143 In unmasked mode, scoreboard will check:
144 - Register `entropy_refresh_hash_cnt` always returns 0
145 '''
146 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800147 tests: ["{name}_entropy_refresh"]
Cindy Cheneb071dc2022-09-13 12:30:19 -0700148 }
149 {
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -0800150 name: error
151 desc: '''
152 Try several error sequences:
153
154 - Update key/prefix/config during absorption/process/squeeze stage.
155 - Write msg to msg_fifo during process/squeeze stage
156 - When in KMAC mode, set the function name to not "KMAC"
157 - Incorrect SHA3 control flow:
158 - Issue Process/Run/Done cmds before issuing Start
159 - Issue Run/Done before issuing Process
160 - Issue Start after issuing Process
161 - If squeezing data, issue Start/Process after issuing Run
162 - Incorrect KMAC configurations (e.g. set KMAC strength as 512).
Udi Jonnalagadda556dd652021-04-29 14:25:20 -0700163 - Provide software inputs during operation of the application interface
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -0800164
165 // TODO: Not all of these errors have been supported yet, and more errors might be
166 // added later.
167 // So this might be split into several error tests later on.
168 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -0700169 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800170 tests: ["{name}_error"]
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -0800171 }
172 {
Cindy Chen10e82b82022-02-14 17:14:58 -0800173 name: key_error
174 desc: ''' Test kmac responses correctly when keymgr app sends request but key is not valid.
175 **Stimulus**:
176 - Configure kmac and send keymgr request, but did not set valid bit for keymgr key
177 input.
178 - Wait randomly clock cycles.
179 - Issue `err_processed`, then wait for the keymgr interface handshake to finish.
180 - Repeat the above sequence a few times.
181 - Issue correct kmac request from app or sw interface.
182
183 **Check**:
184 - Check error related registers including `err_code`, `status`, and `interrupt`.
185 - Check keymgr interface responses with all zero digests and error bit is set.
186 - Check kmac can resume normal functionalities after processing this error case.
187 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -0700188 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800189 tests: ["{name}_key_error"]
Cindy Chen10e82b82022-02-14 17:14:58 -0800190 }
191 {
Cindy Chen621c3312022-02-15 12:18:13 -0800192 name: edn_timeout_error
193 desc: ''' Test kmac responses correctly when EDN response timeout.
Cindy Cheneb071dc2022-09-13 12:30:19 -0700194 Based on kmac app sequence, this sequence configures kmac to ensure an EDN timeout
195 error by writing `entropy_period.wait_timer` and `entropy_period.prescaler` registers.
Cindy Chen621c3312022-02-15 12:18:13 -0800196 **Check**:
197 - Check error related registers including `err_code`, `status`, and `interrupt`.
198 - Check keymgr interface responses with error bit sets to 1.
199 - Check kmac can resume normal functionalities after processing this error case.
200 - Check timeout error will not trigger if the `entropy_mode` is set to SW, or masking
201 is disabled.
202 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -0700203 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800204 tests: ["{name}_edn_timeout_error"]
Cindy Chen621c3312022-02-15 12:18:13 -0800205 }
Cindy Cheneb071dc2022-09-13 12:30:19 -0700206 {
Cindy Chen79e62162022-02-15 21:59:58 -0800207 name: entropy_mode_error
208 desc: ''' Test kmac responses correctly when entropy mode is configured incorrectly.
209 Based on kmac edn_timeout sequence, this sequence write incorrect
210 `ral.cfg_shadowed.entropy_mode` before entropy is fetched.
211 **Check**:
212 - Check error related registers including `err_code`, `status`, and `interrupt`.
213 - Check keymgr interface responses with error bit sets to 1.
214 - Check kmac can resume normal functionalities after processing this error case.
215 - Check timeout error will not trigger if masking is disabled.
216 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -0700217 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800218 tests: ["{name}_entropy_mode_error"]
Cindy Cheneb071dc2022-09-13 12:30:19 -0700219 }
Cindy Chencc15a922022-10-06 11:03:25 -0700220 {
221 name: entropy_ready_error
222 desc: ''' Test kmac responses correctly when entropy_ready field is not set.
223 Based on kmac app sequence, this sequence does not write `1` to
224 `ral.cfg_shadowed.entropy_ready` field before a kmac operation.
225 **Check**:
226 - If masking is enabled and the kmac operation is EDN mode:
227 - If it is a SW operation, check error related registers including `err_code`,
228 `status`, and `interrupt`.
229 - If it is an APP operation, check keymgr interface responses with error bit sets to
230 `1`.
231 - If masking is not enabled or the operation does not require entropy:
232 - Check no error triggered.
233 '''
234 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800235 tests: ["{name}_entropy_ready_error"]
Cindy Chencc15a922022-10-06 11:03:25 -0700236 }
Cindy Chen79e62162022-02-15 21:59:58 -0800237 {
Cindy Chen166d7af2022-02-11 14:48:44 -0800238 name: lc_escalation
239 desc: '''
240 Randomly set `lc_escalate_en` to value that is not `Off` during Kmac operations.
241
242 **Checks**:
243 - Fatal alert fires continuously until reset is issued.
244 - Status fields: `alert_fatal_fault` is set to 1 and `sha3_idle` is reset to 0.
245 - Kmac does not accept any SW or APP requests.
246 - Digest window always output all 0s.
247 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -0700248 stage: V2
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800249 tests: ["{name}_lc_escalation"]
Cindy Chen166d7af2022-02-11 14:48:44 -0800250 }
251 {
Cindy Chen612efc42022-07-25 10:05:32 -0700252 name: stress_all
253 desc: '''
254 - Combine above sequences in one test to run sequentially, except csr sequence and
255 some error tests that disabled scoreboard.
256 - Randomly add reset between each sequence'''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -0700257 stage: V2
Cindy Chen612efc42022-07-25 10:05:32 -0700258 tests: ["kmac_stress_all"]
259 }
260 {
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -0800261 name: throughput
262 desc: '''
263 Measure the throughput of the various hashing calculations and make sure they correspond
264 to the expected throughput range for the design.
265 '''
Michael Schaffnerd1be61b2022-08-23 17:41:35 -0700266 stage: V3
Weicai Yanga1afa1d2022-12-16 16:20:16 -0800267 tests: ["{name}_throughput"]
Udi Jonnalagadda78b3d612020-11-23 16:01:35 -0800268 }
Udi Jonnalagadda95bcc902020-10-29 16:24:34 -0700269 ]
Udi Jonnalagaddac28dae52021-05-26 17:45:33 -0700270
271 covergroups: [
272 {
273 name: config_cg
274 desc: '''
275 Covers that all valid configuration settings for the KMAC have been tested.
276 Individual config settings that will be covered include:
277 - hashing mode (sha3/shake/kmac)
278 - security strength (128/224/256/384/512)
279 - key length (128/192/256/384/512)
280 - message endianness enable/disable
281 - digest endianness enable/disable
282 - XOF mode when using KMAC hashing
283 All valid combinations of the above will also be crossed.
284 '''
285 }
286 {
287 name: msg_len_cg
288 desc: '''
289 Covers various input message length ranges, to ensure that KMAC can operate successfully
290 on different sized messages.
291 The minimum tested msg length is 0 bytes, and the maximum length is 10_000 bytes,
292 we will cover that an acceptable distribution of lengths has been seen, and specifically
293 cover some corner cases (like length 0).
294 '''
295 }
296 {
297 name: output_digest_len_cg
298 desc: '''
299 Similar to the `msg_len_cg`, we also want to cover various output digest lengths to
300 ensure that KMAC can successfully produce outputs of varying sizes.
301 Note that this only applies to XOF functions, as SHA3 functions have a fixed output
302 length.
303 '''
304 }
305 {
306 name: prefix_range_cg
307 desc: '''
308 The prefix used for CSHAKE and KMAC (function_name + customization_string) are only
309 allowed to be valid alphabet letters, or a space character.
310 This covergroup covers that all of these characters have appeared in a prefix value.
311 '''
312 }
313 {
314 name: msgfifo_write_mask_cg
315 desc: '''
316 Covers that the msgfifo has been written using all possible TLUL masks.
317 '''
318 }
319 {
320 name: msgfifo_level_cg
321 desc: '''
322 Covers that all possible fifo statuses have been seen when running different hash
323 operations (like sha3/shake/cshake/kmac), such as various fifo depths, fifo full, and
324 fifo empty.
325 '''
326 }
327 {
328 name: sha3_status_cg
329 desc: '''
330 Covers that all sha3-related status fields have eventually been seen.
331 '''
332 }
333 {
334 name: state_read_mask_cg
335 desc: '''
336 Covers that the state windows have been read using all possible TLUL masks.
337 '''
338 }
339 {
340 name: cmd_process_cg
341 desc: '''
342 Covers that the KMAC can handle seeing a `CmdProcess` command during the following sets
343 of scenarios:
344 - various msgfifo status (full/empty/in between)
345 - while keccak rounds are currently active/inactive
346 '''
347 }
348 {
349 name: sideload_cg
350 desc: '''
351 Covers that the KMAC sees scenarios where the sideloaded key is provided and should be
Cindy Chene9e192a2022-07-14 16:16:39 -0700352 used (`en_sideload==1`, `app_mode==AppKeymgr`), and scenarios where the sideloaded key
353 is provided but should not be used.
Udi Jonnalagaddac28dae52021-05-26 17:45:33 -0700354 '''
355 }
356 {
357 name: app_cg
358 desc: '''
359 Covers several scenarios related to the app interface:
360 - A single data beat is sent
361 - All partial data lengths have been seen (only applies to the last data beat)
362 - Errors are reported through this interface
363 - `Done` signal is sent while keccak rounds are currently active/inactive
364
365 Note that this covergroup will be duplicated once per app interface.
366 '''
367 }
368 {
Cindy Chen9fac57c2022-07-19 11:02:15 -0700369 name: app_sw_cfg_cg
370 desc: '''
371 Covers several scenarios related to the app interface and cfg_shadowed register value:
372 - Hash_mode field value.
373 - Kmac_en field value.
374 - Kstrength field value.
375
376 These sw register settings should not affect kmac app interface calculation.
377 Note that this covergroup will be duplicated once per app interface.
378 '''
379 }
380 {
Cindy Chenf5a882d2022-09-23 16:49:31 -0700381 name: entropy_timer_cg
382 desc: '''
383 Cover the values for the entropy_period register's `prescaler` and `wait_timer` fields.
384 Cross these field ranges with whether the entropy EDN mode is on or off.
385 '''
386 }
387 {
Udi Jonnalagaddac28dae52021-05-26 17:45:33 -0700388 name: edn_cg
389 desc: '''
390 Covers that EDN entropy can be received by KMAC while keccak rounds are active/inactive,
391 crossed with a few entropy configuration values (fast entropy, etc...).
392 '''
393 }
394 {
395 name: error_cg
396 desc: '''
Udi Jonnalagadda46bc1942021-08-13 16:43:53 -0700397 Covers all error scenarios:
398 - ErrKeyNotValid: covers that secret key is invalid when KeyMgr initiates App operation
399 - ErrSwPushedMsgFifo: covers that SW writes the msgfifo while App interface is active
400 - ErrSwIssuedCmdInAppActive: covers that SW writes all possible commands to the KMAC
401 while App interface is active
402 - ErrWaitTimerExpired: covers that the KMAC timed out while waiting for EDN entropy
403 - ErrIncorrectEntropyMode: covers that incorrect entropy modes are detected by the KMAC
404 - ErrUnexpectedModeStrength: covers that 128-bit strength is seen for SHA3, and all but
405 128/256 bit strengths are seen for XOF functions
406 - ErrIncorrectFunctionName: covers that the function name is configured incorrectly
407 when KMAC mode is enabled
408 - ErrSwCmdSequence: covers that SW issues commands to the KMAC out of order
Udi Jonnalagaddac28dae52021-05-26 17:45:33 -0700409 '''
410 }
411 ]
Udi Jonnalagadda95bcc902020-10-29 16:24:34 -0700412}