Software APIs
kmac_testutils.c
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#include "sw/device/lib/testing/kmac_testutils.h"
6
8#include "sw/device/lib/testing/test_framework/check.h"
9
10status_t kmac_testutils_config(dif_kmac_t *kmac, bool sideload) {
11 dif_kmac_config_t config = {
12 // Always mask Keccak operations, even if not processing a secret key.
13 .entropy_fast_process = false,
14 // Leave message as the little-endian default.
15 .message_big_endian = false,
16 // Leave output as the little-endian default.
17 .output_big_endian = false,
18 // Use a sideloaded key if the caller requested to.
19 .sideload = sideload,
20 // Mask the message upon loading.
21 .msg_mask = true,
22 };
23
24 dif_kmac_entropy_config_t entropy_config = {
25 // Use software-provided "entropy" to avoid waiting for EDN.
26 .entropy_mode = kDifKmacEntropyModeSoftware,
27 // Don't ignore reseed requests from software.
28 .ignore_cmd_entropy_req = false,
29 // This can be ignored as we use the Software Mode.
30 .edn_mode_refresh_threshold = 0,
31 // Any seed is suitable for testing.
32 .sw_mode_entropy_seed = {0xb153e3fe, 0x09596819, 0x3e85a6e8, 0xb6dcdaba,
33 0x50dc409c, 0x11e1ebd1},
34 };
35
36 TRY(dif_kmac_configure(kmac, config));
37 TRY(dif_kmac_configure_entropy(kmac, entropy_config));
38 return OK_STATUS();
39}
40
41status_t kmac_testutils_kmac(const dif_kmac_t *kmac,
42 const dif_kmac_mode_kmac_t mode,
43 const dif_kmac_key_t *key,
44 const char *custom_string,
45 const size_t custom_string_len,
46 const char *message, const size_t message_len,
47 const size_t output_len, uint32_t *output,
48 uint32_t *capacity) {
49 // Initialize customization string.
50 dif_kmac_customization_string_t kmac_custom_string;
51 TRY(dif_kmac_customization_string_init(custom_string, custom_string_len,
52 &kmac_custom_string));
53
54 // Start the KMAC operation and check that KMAC doesn't report an error.
55 dif_kmac_operation_state_t operation_state;
56 TRY(dif_kmac_mode_kmac_start(kmac, &operation_state, mode, output_len, key,
57 &kmac_custom_string));
58 TRY(kmac_testutils_check_error(kmac));
59
60 // Pass the entire message to KMAC ("absorb" stage) and check that KMAC
61 // doesn't report an error.
62 TRY(dif_kmac_absorb(kmac, &operation_state, message, message_len, NULL));
63 TRY(kmac_testutils_check_error(kmac));
64
65 // Get the output ("squeeze" stage) and check that KMAC doesn't report an
66 // error.
67 TRY(dif_kmac_squeeze(kmac, &operation_state, output, output_len, NULL,
68 capacity));
69 TRY(kmac_testutils_check_error(kmac));
70
71 // End the operation and check that KMAC doesn't report an error.
72 TRY(dif_kmac_end(kmac, &operation_state));
73 TRY(kmac_testutils_check_error(kmac));
74
75 return OK_STATUS();
76}
77
78status_t kmac_testutils_check_error(const dif_kmac_t *kmac) {
79 bool error;
80 TRY(dif_kmac_has_error_occurred(kmac, &error));
81
82 // If no error has occurred, return early with OK.
83 if (!error) {
84 return OK_STATUS();
85 }
86
87 // Obtain more information on the error.
89 uint32_t info;
90 TRY(dif_kmac_get_error(kmac, &err, &info));
91
92 // Clear the error IRQ.
93 TRY(dif_kmac_clear_err_irq(kmac));
94
95 // Inform HW that we have handled the error.
96 TRY(dif_kmac_err_processed(kmac));
97
98 // Return with a status based on the error code.
99 switch (err) {
101 return FAILED_PRECONDITION();
102 default:
103 return INTERNAL();
104 }
105}