Software APIs
dif_kmac.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
6
7#include <assert.h>
8
12
13#include "hw/top/kmac_regs.h" // Generated.
14
15enum {
16 /**
17 * The maximum amount of usable bits in the output state.
18 *
19 * This constant may be assumed to be a multiple of 32.
20 *
21 * The actual number of usable bits may be lower than the value defined
22 * depending on the mode in use. The intent is that this constant is useful
23 * for sizing fixed length buffers.
24 *
25 * Formula for the rate in bits is:
26 *
27 * r = 1600 - c
28 *
29 * Where c is the capacity (the security level in bits multiplied by two).
30 *
31 * The lowest security level is 128 (e.g. SHAKE128).
32 */
33 kDifKmacMaximumBitRate = 1600 - (2 * 128),
34};
35
36dif_result_t dif_kmac_customization_string_init(
37 const char *data, size_t len, dif_kmac_customization_string_t *out) {
38 if ((data == NULL && len != 0) || out == NULL) {
39 return kDifBadArg;
40 }
41
43 return kDifBadArg;
44 }
45
46 static_assert(kDifKmacMaxCustomizationStringLen <= UINT16_MAX / 8,
47 "length requires more than 3 bytes to left encode");
48 static_assert(ARRAYSIZE(out->buffer) >= kDifKmacMaxCustomizationStringLen + 3,
49 "buffer is not large enough");
50
51 // Left encode length in bits.
52 uint16_t bits = ((uint16_t)len) * 8;
53 char *buffer = out->buffer;
54 if (bits <= UINT8_MAX) {
55 out->length = len + 2;
56 *buffer++ = 1;
57 *buffer++ = (char)bits;
58 } else {
59 out->length = len + 3;
60 *buffer++ = 2;
61 // Most significant byte is first (i.e. big-endian).
62 *buffer++ = (char)(bits >> 8);
63 *buffer++ = (char)bits;
64 }
65
66 memcpy(buffer, data, len);
67
68 return kDifOk;
69}
70
71dif_result_t dif_kmac_function_name_init(const char *data, size_t len,
73 if ((data == NULL && len != 0) || out == NULL) {
74 return kDifBadArg;
75 }
76
78 return kDifBadArg;
79 }
80
81 static_assert(kDifKmacMaxFunctionNameLen <= UINT8_MAX / 8,
82 "length requires more than 2 bytes to left encode");
83 static_assert(ARRAYSIZE(out->buffer) >= kDifKmacMaxFunctionNameLen + 2,
84 "buffer is not large enough");
85
86 // Length of the data to be stored into buffer.
87 out->length = len + 2;
88
89 // Left encode length in bits.
90 out->buffer[0] = 1;
91 out->buffer[1] = (char)(len * 8);
92
93 memcpy(&out->buffer[2], data, len);
94
95 return kDifOk;
96}
97
98/**
99 * Report whether the hardware is currently idle.
100 *
101 * If the hardware is not idle then the `CFG` register is locked.
102 *
103 * @param kmac Handle.
104 * @returns Whether the hardware is currently idle or not.
105 */
106static bool is_state_idle(const dif_kmac_t *kmac) {
107 uint32_t reg = mmio_region_read32(kmac->base_addr, KMAC_STATUS_REG_OFFSET);
108 return bitfield_bit32_read(reg, KMAC_STATUS_SHA3_IDLE_BIT);
109}
110
111/**
112 * Report whether the hardware is currently in the absorb state and accepting
113 * writes to the message FIFO.
114 *
115 * Note that writes to the message FIFO may still block if it is full.
116 *
117 * @param kmac Handle.
118 * @returns Whether the hardware is currently absorbing or not.
119 */
120static bool is_state_absorb(const dif_kmac_t *kmac) {
121 uint32_t reg = mmio_region_read32(kmac->base_addr, KMAC_STATUS_REG_OFFSET);
122 return bitfield_bit32_read(reg, KMAC_STATUS_SHA3_ABSORB_BIT);
123}
124
125/**
126 * Report whether the hardware is currently in the squeeze state which means
127 * that the output state is valid and may be read by software.
128 *
129 * @param kmac Handle.
130 * @returns Whether the hardware is currently in the squeeze state or not.
131 */
132static bool is_state_squeeze(const dif_kmac_t *kmac) {
133 uint32_t reg = mmio_region_read32(kmac->base_addr, KMAC_STATUS_REG_OFFSET);
134 return bitfield_bit32_read(reg, KMAC_STATUS_SHA3_SQUEEZE_BIT);
135}
136
137dif_result_t dif_kmac_has_error_occurred(const dif_kmac_t *kmac, bool *error) {
138 if (kmac == NULL) {
139 return kDifBadArg;
140 }
141 uint32_t reg =
142 mmio_region_read32(kmac->base_addr, KMAC_INTR_STATE_REG_OFFSET);
143 *error = bitfield_bit32_read(reg, KMAC_INTR_STATE_KMAC_ERR_BIT);
144 return kDifOk;
145}
146
147dif_result_t dif_kmac_clear_err_irq(const dif_kmac_t *kmac) {
148 if (kmac == NULL) {
149 return kDifBadArg;
150 }
151 uint32_t reg = 0;
152 reg = bitfield_bit32_write(reg, KMAC_INTR_STATE_KMAC_ERR_BIT, true);
153 mmio_region_write32(kmac->base_addr, KMAC_INTR_STATE_REG_OFFSET, reg);
154 return kDifOk;
155}
156
157dif_result_t dif_kmac_poll_status(const dif_kmac_t *kmac, uint32_t flag) {
158 while (true) {
159 uint32_t reg = mmio_region_read32(kmac->base_addr, KMAC_STATUS_REG_OFFSET);
160 if (bitfield_bit32_read(reg, flag)) {
161 break;
162 }
163 bool error;
164 DIF_RETURN_IF_ERROR(dif_kmac_has_error_occurred(kmac, &error));
165 if (error) {
166 return kDifError;
167 }
168 }
169 return kDifOk;
170}
171
172dif_result_t dif_kmac_configure(dif_kmac_t *kmac, dif_kmac_config_t config) {
173 if (kmac == NULL) {
174 return kDifBadArg;
175 }
176
177 bool locked;
178 DIF_RETURN_IF_ERROR(dif_kmac_config_is_locked(kmac, &locked));
179 if (locked) {
180 return kDifLocked;
181 }
182
183 // Write configuration register.
184 uint32_t cfg_reg = 0;
185 cfg_reg = bitfield_bit32_write(cfg_reg, KMAC_CFG_SHADOWED_MSG_ENDIANNESS_BIT,
186 config.message_big_endian);
187 cfg_reg =
188 bitfield_bit32_write(cfg_reg, KMAC_CFG_SHADOWED_STATE_ENDIANNESS_BIT,
189 config.output_big_endian);
190 cfg_reg =
191 bitfield_bit32_write(cfg_reg, KMAC_CFG_SHADOWED_ENTROPY_FAST_PROCESS_BIT,
192 config.entropy_fast_process);
193 cfg_reg = bitfield_bit32_write(cfg_reg, KMAC_CFG_SHADOWED_SIDELOAD_BIT,
194 config.sideload);
195 cfg_reg = bitfield_bit32_write(cfg_reg, KMAC_CFG_SHADOWED_MSG_MASK_BIT,
196 config.msg_mask);
197
198 mmio_region_write32_shadowed(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET,
199 cfg_reg);
200
201 return kDifOk;
202}
203
204dif_result_t dif_kmac_configure_entropy(dif_kmac_t *kmac,
206 if (kmac == NULL) {
207 return kDifBadArg;
208 }
209
210 bool locked;
211 DIF_RETURN_IF_ERROR(dif_kmac_entropy_config_is_locked(kmac, &locked));
212 if (locked) {
213 return kDifLocked;
214 }
215
216 // Read the entropy configuration register to know if this is the first time
217 // after reset we configure it based on the Entropy Boot Mode bit.
218 bool first_after_reset;
219 uint32_t entropy_cfg_reg =
220 mmio_region_read32(kmac->base_addr, KMAC_ENTROPY_CFG_SHADOWED_REG_OFFSET);
221 first_after_reset = bitfield_bit32_read(
222 entropy_cfg_reg, KMAC_ENTROPY_CFG_SHADOWED_ENTROPY_BOOT_MODE_BIT);
223
224 // Write entropy configuration register. The Entropy Boot Mode bit is RW0C, we
225 // only ever clear it.
226 entropy_cfg_reg = bitfield_bit32_write(
227 0, KMAC_ENTROPY_CFG_SHADOWED_ENTROPY_BOOT_MODE_BIT, 0);
228 entropy_cfg_reg = bitfield_bit32_write(
229 entropy_cfg_reg, KMAC_ENTROPY_CFG_SHADOWED_ENTROPY_MODE_BIT,
230 config.entropy_mode);
231 entropy_cfg_reg = bitfield_bit32_write(
232 entropy_cfg_reg, KMAC_ENTROPY_CFG_SHADOWED_IGNORE_CMD_ENTROPY_REQ_BIT,
234 entropy_cfg_reg = bitfield_field32_write(
235 entropy_cfg_reg,
236 KMAC_ENTROPY_CFG_SHADOWED_EDN_MODE_REFRESH_THRESHOLD_FIELD,
238
239 mmio_region_write32_shadowed(
240 kmac->base_addr, KMAC_ENTROPY_CFG_SHADOWED_REG_OFFSET, entropy_cfg_reg);
241
242 // If the register is written the first time after a reset, a reseed operation
243 // will be triggered automatically. Otherwise trigger one now to complete a
244 // potential Entropy Mode switch.
245 if (!first_after_reset) {
246 uint32_t cmd_reg = bitfield_bit32_write(0, KMAC_CMD_ENTROPY_REQ_BIT, 1);
247 mmio_region_write32(kmac->base_addr, KMAC_CMD_REG_OFFSET, cmd_reg);
248 }
249
250 // In Software Mode, the PRNG is now waiting for a new seed to be provided via
251 // the entropy seed register.
252 if (config.entropy_mode == kDifKmacEntropyModeSoftware) {
253 for (int i = 0; i < kDifKmacEntropySeedWords; ++i) {
254 mmio_region_write32(kmac->base_addr, KMAC_ENTROPY_SEED_REG_OFFSET,
255 config.sw_mode_entropy_seed[i]);
256 }
257 }
258
259 return kDifOk;
260}
261
262/**
263 * Calculate the rate (r) in bits from the given security level.
264 *
265 * @param security_level Security level in bits.
266 * @returns Rate in bits.
267 */
268static uint32_t calculate_rate_bits(uint32_t security_level) {
269 // Formula for the rate in bits is:
270 //
271 // r = 1600 - c
272 //
273 // Where c is the capacity (the security level in bits multiplied by two).
274 return 1600 - 2 * security_level;
275}
276
277dif_result_t dif_kmac_mode_sha3_start(
278 const dif_kmac_t *kmac, dif_kmac_operation_state_t *operation_state,
280 if (kmac == NULL || operation_state == NULL) {
281 return kDifBadArg;
282 }
283
284 // Set key strength and calculate rate (r) and digest length (d) in 32-bit
285 // words.
286 uint32_t kstrength;
287 switch (mode) {
289 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L224;
290 operation_state->offset = 0;
291 operation_state->r = calculate_rate_bits(224) / 32;
292 operation_state->d = 224 / 32;
293 break;
295 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L256;
296 operation_state->offset = 0;
297 operation_state->r = calculate_rate_bits(256) / 32;
298 operation_state->d = 256 / 32;
299 break;
301 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L384;
302 operation_state->offset = 0;
303 operation_state->r = calculate_rate_bits(384) / 32;
304 operation_state->d = 384 / 32;
305 break;
307 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L512;
308 operation_state->offset = 0;
309 operation_state->r = calculate_rate_bits(512) / 32;
310 operation_state->d = 512 / 32;
311 break;
312 default:
313 return kDifBadArg;
314 }
315
316 // Hardware must be idle to start an operation.
317 if (!is_state_idle(kmac)) {
318 return kDifError;
319 }
320
321 operation_state->squeezing = false;
322 operation_state->append_d = false;
323
324 // Configure SHA-3 mode with the given strength.
325 uint32_t cfg_reg =
326 mmio_region_read32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET);
327 cfg_reg = bitfield_field32_write(cfg_reg, KMAC_CFG_SHADOWED_KSTRENGTH_FIELD,
328 kstrength);
329 cfg_reg = bitfield_field32_write(cfg_reg, KMAC_CFG_SHADOWED_MODE_FIELD,
330 KMAC_CFG_SHADOWED_MODE_VALUE_SHA3);
331 mmio_region_write32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET, cfg_reg);
332 mmio_region_write32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET, cfg_reg);
333
334 // Issue start command.
335 uint32_t cmd_reg =
336 bitfield_field32_write(0, KMAC_CMD_CMD_FIELD, KMAC_CMD_CMD_VALUE_START);
337 mmio_region_write32(kmac->base_addr, KMAC_CMD_REG_OFFSET, cmd_reg);
338
339 // Poll until the status register is in the 'absorb' state.
340 return dif_kmac_poll_status(kmac, KMAC_STATUS_SHA3_ABSORB_BIT);
341}
342
343dif_result_t dif_kmac_mode_shake_start(
344 const dif_kmac_t *kmac, dif_kmac_operation_state_t *operation_state,
346 if (kmac == NULL || operation_state == NULL) {
347 return kDifBadArg;
348 }
349
350 // Set key strength and calculate rate (r).
351 uint32_t kstrength;
352 switch (mode) {
354 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L128;
355 operation_state->r = calculate_rate_bits(128) / 32;
356 break;
358 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L256;
359 operation_state->r = calculate_rate_bits(256) / 32;
360 break;
361 default:
362 return kDifBadArg;
363 }
364
365 // Hardware must be idle to start an operation.
366 if (!is_state_idle(kmac)) {
367 return kDifError;
368 }
369 operation_state->squeezing = false;
370 operation_state->append_d = false;
371 operation_state->d = 0; // Zero indicates variable digest length.
372 operation_state->offset = 0;
373
374 // Configure SHAKE mode with the given strength.
375 uint32_t cfg_reg =
376 mmio_region_read32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET);
377 cfg_reg = bitfield_field32_write(cfg_reg, KMAC_CFG_SHADOWED_KSTRENGTH_FIELD,
378 kstrength);
379 cfg_reg = bitfield_field32_write(cfg_reg, KMAC_CFG_SHADOWED_MODE_FIELD,
380 KMAC_CFG_SHADOWED_MODE_VALUE_SHAKE);
381 mmio_region_write32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET, cfg_reg);
382 mmio_region_write32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET, cfg_reg);
383
384 // Issue start command.
385 uint32_t cmd_reg =
386 bitfield_field32_write(0, KMAC_CMD_CMD_FIELD, KMAC_CMD_CMD_VALUE_START);
387 mmio_region_write32(kmac->base_addr, KMAC_CMD_REG_OFFSET, cmd_reg);
388
389 return dif_kmac_poll_status(kmac, KMAC_STATUS_SHA3_ABSORB_BIT);
390}
391
392dif_result_t dif_kmac_mode_cshake_start(
393 const dif_kmac_t *kmac, dif_kmac_operation_state_t *operation_state,
396 if (kmac == NULL || operation_state == NULL) {
397 return kDifBadArg;
398 }
399
400 // Use SHAKE if both N and S are empty strings.
401 bool n_is_empty = n == NULL || (n->buffer[0] == 1 && n->buffer[1] == 0);
402 bool s_is_empty = s == NULL || (s->buffer[0] == 1 && s->buffer[1] == 0);
403 if (n_is_empty && s_is_empty) {
404 switch (mode) {
406 return dif_kmac_mode_shake_start(kmac, operation_state,
409 return dif_kmac_mode_shake_start(kmac, operation_state,
411 default:
412 return kDifBadArg;
413 }
414 }
415
416 // Set key strength and calculate rate (r).
417 uint32_t kstrength;
418 switch (mode) {
420 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L128;
421 operation_state->r = calculate_rate_bits(128) / 32;
422 break;
424 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L256;
425 operation_state->r = calculate_rate_bits(256) / 32;
426 break;
427 default:
428 return kDifBadArg;
429 }
430
431 // Hardware must be idle to start an operation.
432 if (!is_state_idle(kmac)) {
433 return kDifError;
434 }
435 operation_state->squeezing = false;
436 operation_state->append_d = false;
437 operation_state->d = 0; // Zero indicates variable digest length.
438 operation_state->offset = 0;
439
440 // Configure cSHAKE mode with the given strength.
441 uint32_t cfg_reg =
442 mmio_region_read32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET);
443 cfg_reg = bitfield_field32_write(cfg_reg, KMAC_CFG_SHADOWED_KSTRENGTH_FIELD,
444 kstrength);
445 cfg_reg = bitfield_field32_write(cfg_reg, KMAC_CFG_SHADOWED_MODE_FIELD,
446 KMAC_CFG_SHADOWED_MODE_VALUE_CSHAKE);
447 mmio_region_write32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET, cfg_reg);
448 mmio_region_write32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET, cfg_reg);
449
450 // Calculate PREFIX register values.
451 uint32_t prefix_regs[11] = {0};
452 uint8_t *prefix_data = (uint8_t *)prefix_regs;
453 if (n == NULL || n->length < 3) {
454 // Append left encoded empty string.
455 prefix_data[0] = 1;
456 prefix_data[1] = 0;
457 prefix_data += 2;
458 } else {
459 memcpy(prefix_data, n->buffer, n->length);
460 prefix_data += n->length;
461 }
462 if (s == NULL || s->length == 0) {
463 // Append left encoded empty string.
464 prefix_data[0] = 1;
465 prefix_data[1] = 0;
466 } else {
467 memcpy(prefix_data, s->buffer, s->length);
468 }
469
470 // Write PREFIX register values.
471 const mmio_region_t base = kmac->base_addr;
472 mmio_region_write32(base, KMAC_PREFIX_0_REG_OFFSET, prefix_regs[0]);
473 mmio_region_write32(base, KMAC_PREFIX_1_REG_OFFSET, prefix_regs[1]);
474 mmio_region_write32(base, KMAC_PREFIX_2_REG_OFFSET, prefix_regs[2]);
475 mmio_region_write32(base, KMAC_PREFIX_3_REG_OFFSET, prefix_regs[3]);
476 mmio_region_write32(base, KMAC_PREFIX_4_REG_OFFSET, prefix_regs[4]);
477 mmio_region_write32(base, KMAC_PREFIX_5_REG_OFFSET, prefix_regs[5]);
478 mmio_region_write32(base, KMAC_PREFIX_6_REG_OFFSET, prefix_regs[6]);
479 mmio_region_write32(base, KMAC_PREFIX_7_REG_OFFSET, prefix_regs[7]);
480 mmio_region_write32(base, KMAC_PREFIX_8_REG_OFFSET, prefix_regs[8]);
481 mmio_region_write32(base, KMAC_PREFIX_9_REG_OFFSET, prefix_regs[9]);
482 mmio_region_write32(base, KMAC_PREFIX_10_REG_OFFSET, prefix_regs[10]);
483
484 // Issue start command.
485 uint32_t cmd_reg =
486 bitfield_field32_write(0, KMAC_CMD_CMD_FIELD, KMAC_CMD_CMD_VALUE_START);
487 mmio_region_write32(kmac->base_addr, KMAC_CMD_REG_OFFSET, cmd_reg);
488
489 return dif_kmac_poll_status(kmac, KMAC_STATUS_SHA3_ABSORB_BIT);
490}
491
492dif_result_t dif_kmac_mode_kmac_start(
493 const dif_kmac_t *kmac, dif_kmac_operation_state_t *operation_state,
494 dif_kmac_mode_kmac_t mode, size_t l, const dif_kmac_key_t *k,
496 if (kmac == NULL || operation_state == NULL || k == NULL ||
498 return kDifBadArg;
499 }
500
501 // Set key strength and calculate rate (r).
502 uint32_t kstrength;
503 switch (mode) {
505 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L128;
506 operation_state->r = calculate_rate_bits(128) / 32;
507 break;
509 kstrength = KMAC_CFG_SHADOWED_KSTRENGTH_VALUE_L256;
510 operation_state->r = calculate_rate_bits(256) / 32;
511 break;
512 default:
513 return kDifBadArg;
514 }
515 operation_state->squeezing = false;
516 operation_state->offset = 0;
517 operation_state->d = l;
518 operation_state->append_d = true;
519
520 uint32_t key_len;
521 switch (k->length) {
523 key_len = KMAC_KEY_LEN_LEN_VALUE_KEY128;
524 break;
526 key_len = KMAC_KEY_LEN_LEN_VALUE_KEY192;
527 break;
529 key_len = KMAC_KEY_LEN_LEN_VALUE_KEY256;
530 break;
532 key_len = KMAC_KEY_LEN_LEN_VALUE_KEY384;
533 break;
535 key_len = KMAC_KEY_LEN_LEN_VALUE_KEY512;
536 break;
537 default:
538 return kDifBadArg;
539 }
540
541 // Hardware must be idle to start an operation.
542 if (!is_state_idle(kmac)) {
543 return kDifError;
544 }
545 // Set key length and shares.
546 mmio_region_write32(kmac->base_addr, KMAC_KEY_LEN_REG_OFFSET, key_len);
547 for (int i = 0; i < ARRAYSIZE(k->share0); ++i) {
548 mmio_region_write32(kmac->base_addr,
549 KMAC_KEY_SHARE0_0_REG_OFFSET +
550 (ptrdiff_t)i * (ptrdiff_t)sizeof(uint32_t),
551 k->share0[i]);
552 mmio_region_write32(kmac->base_addr,
553 KMAC_KEY_SHARE1_0_REG_OFFSET +
554 (ptrdiff_t)i * (ptrdiff_t)sizeof(uint32_t),
555 k->share1[i]);
556 }
557
558 // Configure cSHAKE mode with the given strength and enable KMAC mode.
559 uint32_t cfg_reg =
560 mmio_region_read32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET);
561 cfg_reg = bitfield_bit32_write(cfg_reg, KMAC_CFG_SHADOWED_KMAC_EN_BIT, true);
562 cfg_reg = bitfield_field32_write(cfg_reg, KMAC_CFG_SHADOWED_KSTRENGTH_FIELD,
563 kstrength);
564 cfg_reg = bitfield_field32_write(cfg_reg, KMAC_CFG_SHADOWED_MODE_FIELD,
565 KMAC_CFG_SHADOWED_MODE_VALUE_CSHAKE);
566 mmio_region_write32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET, cfg_reg);
567 mmio_region_write32(kmac->base_addr, KMAC_CFG_SHADOWED_REG_OFFSET, cfg_reg);
568
569 // Initialize prefix registers with function name ("KMAC") and empty
570 // customization string. The empty customization string will be overwritten if
571 // a non-empty string is provided.
572 uint32_t prefix_regs[11] = {
573 0x4D4B2001, // 1 32 'K' 'M'
574 0x00014341, // 'A' 'C' 1 0
575 };
576
577 // Encoded customization string (s) must be at least 3 bytes long if it is not
578 // the empty string.
579 if (s != NULL && s->length >= 3) {
580 // First two bytes overwrite the pre-encoded empty customization string.
581 prefix_regs[1] &= 0xFFFF;
582 prefix_regs[1] |= (uint32_t)((uint8_t)s->buffer[0]) << 16;
583 prefix_regs[1] |= (uint32_t)((uint8_t)s->buffer[1]) << 24;
584 memcpy(&prefix_regs[2], &s->buffer[2], s->length - 2);
585 }
586
587 // Write PREFIX register values.
588 const mmio_region_t base = kmac->base_addr;
589 mmio_region_write32(base, KMAC_PREFIX_0_REG_OFFSET, prefix_regs[0]);
590 mmio_region_write32(base, KMAC_PREFIX_1_REG_OFFSET, prefix_regs[1]);
591 mmio_region_write32(base, KMAC_PREFIX_2_REG_OFFSET, prefix_regs[2]);
592 mmio_region_write32(base, KMAC_PREFIX_3_REG_OFFSET, prefix_regs[3]);
593 mmio_region_write32(base, KMAC_PREFIX_4_REG_OFFSET, prefix_regs[4]);
594 mmio_region_write32(base, KMAC_PREFIX_5_REG_OFFSET, prefix_regs[5]);
595 mmio_region_write32(base, KMAC_PREFIX_6_REG_OFFSET, prefix_regs[6]);
596 mmio_region_write32(base, KMAC_PREFIX_7_REG_OFFSET, prefix_regs[7]);
597 mmio_region_write32(base, KMAC_PREFIX_8_REG_OFFSET, prefix_regs[8]);
598 mmio_region_write32(base, KMAC_PREFIX_9_REG_OFFSET, prefix_regs[9]);
599 mmio_region_write32(base, KMAC_PREFIX_10_REG_OFFSET, prefix_regs[10]);
600
601 // Issue start command.
602 uint32_t cmd_reg =
603 bitfield_field32_write(0, KMAC_CMD_CMD_FIELD, KMAC_CMD_CMD_VALUE_START);
604 mmio_region_write32(kmac->base_addr, KMAC_CMD_REG_OFFSET, cmd_reg);
605
606 return dif_kmac_poll_status(kmac, KMAC_STATUS_SHA3_ABSORB_BIT);
607}
608
609static void msg_fifo_write(const dif_kmac_t *kmac, const unsigned char *data,
610 size_t len) {
611 // Copy message using aligned word sized loads and stores where possible to
612 // improve performance. Note: the parts of the message copied a byte at a time
613 // will not be byte swapped in big-endian mode.
614 for (; len != 0 && ((uintptr_t)data) % sizeof(uint32_t); --len) {
615 mmio_region_write8(kmac->base_addr, KMAC_MSG_FIFO_REG_OFFSET, *data++);
616 }
617 for (; len >= sizeof(uint32_t); len -= sizeof(uint32_t)) {
618 mmio_region_write32(kmac->base_addr, KMAC_MSG_FIFO_REG_OFFSET,
619 read_32(data));
620 data += sizeof(uint32_t);
621 }
622 for (; len != 0; --len) {
623 mmio_region_write8(kmac->base_addr, KMAC_MSG_FIFO_REG_OFFSET, *data++);
624 }
625}
626
627dif_result_t dif_kmac_absorb(const dif_kmac_t *kmac,
628 dif_kmac_operation_state_t *operation_state,
629 const void *msg, size_t len, size_t *processed) {
630 // Set the number of bytes processed to 0.
631 if (processed != NULL) {
632 *processed = 0;
633 }
634
635 if (kmac == NULL || operation_state == NULL || (msg == NULL && len != 0)) {
636 return kDifBadArg;
637 }
638
639 // Check that an operation has been started.
640 if (operation_state->r == 0) {
641 return kDifError;
642 }
643
644 // Poll until the status register is in the 'absorb' state.
645 if (!is_state_absorb(kmac)) {
646 return kDifError;
647 }
648
649 // Copy message using aligned word sized loads and stores where possible to
650 // improve performance. Note: the parts of the message copied a byte at a time
651 // will not be byte swapped in big-endian mode.
652 const unsigned char *data = (const unsigned char *)msg;
653 dif_kmac_status_t status;
654 while (len > 0) {
655 // Read the status register.
656 DIF_RETURN_IF_ERROR(dif_kmac_get_status(kmac, &status));
657
658 // Calculate the remaining space in the message FIFO based on the
659 // `FIFO_DEPTH` status field.
660 size_t free_entries = (KMAC_PARAM_NUM_ENTRIES_MSG_FIFO - status.fifo_depth);
661 size_t max_len = free_entries * KMAC_PARAM_NUM_BYTES_MSG_FIFO_ENTRY;
662 size_t write_len = (len < max_len) ? len : max_len;
663 msg_fifo_write(kmac, data, write_len);
664 data += write_len;
665 len -= write_len;
666
667 // If `processed` is non-null, do not continue after the first iteration;
668 // return the number of bytes written and `kDifKmacIncomplete`.
669 if (processed != NULL) {
670 *processed = write_len;
671 break;
672 }
673 }
674
675 return kDifOk;
676}
677
678dif_result_t dif_kmac_squeeze(const dif_kmac_t *kmac,
679 dif_kmac_operation_state_t *operation_state,
680 uint32_t *out, size_t len, size_t *processed,
681 uint32_t *capacity) {
682 if (kmac == NULL || operation_state == NULL || (out == NULL && len != 0)) {
683 return kDifBadArg;
684 }
685
686 // Set `processed` to 0 so we can return early without setting it again.
687 if (processed != NULL) {
688 *processed = 0;
689 }
690
691 const mmio_region_t base = kmac->base_addr;
692
693 // Move into squeezing state (if not already in it).
694 // Do this even if the length requested is 0 or too big.
695 if (!operation_state->squeezing) {
696 if (operation_state->append_d) {
697 // The KMAC operation requires that the output length (d) in bits be right
698 // encoded and appended to the end of the message.
699 // Note: kDifKmacMaxOutputLenWords could be reduced to make this code
700 // simpler. For example, a maximum of `(UINT16_MAX - 32) / 32` (just under
701 // 8 KiB) would mean that d is guaranteed to be less than 0xFFFF.
702 uint32_t d = operation_state->d * 32;
703 int len = 1 + (d > 0xFF) + (d > 0xFFFF) + (d > 0xFFFFFF);
704 int shift = (len - 1) * 8;
705 while (shift >= 8) {
706 mmio_region_write8(base, KMAC_MSG_FIFO_REG_OFFSET,
707 (uint8_t)(d >> shift));
708 shift -= 8;
709 }
710 mmio_region_write8(base, KMAC_MSG_FIFO_REG_OFFSET, (uint8_t)d);
711 mmio_region_write8(base, KMAC_MSG_FIFO_REG_OFFSET, (uint8_t)len);
712 }
713 operation_state->squeezing = true;
714
715 // Issue squeeze command.
716 uint32_t cmd_reg = bitfield_field32_write(0, KMAC_CMD_CMD_FIELD,
717 KMAC_CMD_CMD_VALUE_PROCESS);
718 mmio_region_write32(base, KMAC_CMD_REG_OFFSET, cmd_reg);
719 }
720
721 // If the operation has a fixed length output then the total number of bytes
722 // requested must not exceed that length.
723 if (operation_state->d != 0 &&
724 len > (operation_state->d - operation_state->offset)) {
725 return kDifError;
726 }
727
728 if (len == 0) {
729 return kDifOk;
730 }
731
732 while (len > 0) {
733 size_t n = len;
734 size_t remaining = operation_state->r - operation_state->offset;
735 if (operation_state->d != 0 && operation_state->d < operation_state->r) {
736 remaining = operation_state->d - operation_state->offset;
737 }
738 if (n > remaining) {
739 n = remaining;
740 }
741 if (n == 0) {
742 // Reduce the digest length to reflect consumed output state.
743 if (operation_state->d != 0) {
744 if (operation_state->d <= operation_state->r) {
745 return kDifError;
746 }
747 operation_state->d -= operation_state->r;
748 }
749
750 // Issue run command to generate more state.
751 uint32_t cmd_reg =
752 bitfield_field32_write(0, KMAC_CMD_CMD_FIELD, KMAC_CMD_CMD_VALUE_RUN);
753 mmio_region_write32(base, KMAC_CMD_REG_OFFSET, cmd_reg);
754 operation_state->offset = 0;
755 continue;
756 }
757
758 // Poll the status register until in the 'squeeze' state.
760 dif_kmac_poll_status(kmac, KMAC_STATUS_SHA3_SQUEEZE_BIT));
761
762 ptrdiff_t offset =
763 KMAC_STATE_REG_OFFSET +
764 (ptrdiff_t)operation_state->offset * (ptrdiff_t)sizeof(uint32_t);
765 for (size_t i = 0; i < n; ++i) {
766 // Read both shares from state register and combine using XOR.
767 uint32_t share0 = mmio_region_read32(base, offset);
768 uint32_t share1 =
769 mmio_region_read32(base, offset + kDifKmacStateShareOffset);
770 *out++ = share0 ^ share1;
771 offset += sizeof(uint32_t);
772 }
773 operation_state->offset += n;
774 len -= n;
775 if (processed != NULL) {
776 *processed += n;
777 }
778 // Read also the capacity of the state, if non-NULL buffer is given.
779 // This is only useful for testing that capacity is not leaked during
780 // sideloaded KMAC operations.
781 if (capacity != NULL) {
782 ptrdiff_t capacity_offset =
783 KMAC_STATE_REG_OFFSET +
784 (ptrdiff_t)operation_state->r * (ptrdiff_t)sizeof(uint32_t);
785 for (int i = 0; i < kDifKmacStateWords - operation_state->r; ++i) {
786 uint32_t share0 = mmio_region_read32(base, capacity_offset);
787 uint32_t share1 = mmio_region_read32(
788 base, capacity_offset + kDifKmacStateShareOffset);
789 *capacity++ = share0 ^ share1;
790 capacity_offset += sizeof(uint32_t);
791 }
792 }
793 }
794 return kDifOk;
795}
796
797dif_result_t dif_kmac_end(const dif_kmac_t *kmac,
798 dif_kmac_operation_state_t *operation_state) {
799 if (kmac == NULL || operation_state == NULL) {
800 return kDifBadArg;
801 }
802
803 // The hardware should (must?) complete squeeze operation before the DONE
804 // command is issued.
805 if (!operation_state->squeezing) {
806 return kDifError;
807 }
808 while (true) {
809 if (is_state_squeeze(kmac)) {
810 break;
811 }
812 // TODO(#6248): check for error.
813 }
814
815 // Issue done command.
816 uint32_t cmd_reg =
817 bitfield_field32_write(0, KMAC_CMD_CMD_FIELD, KMAC_CMD_CMD_VALUE_DONE);
818 mmio_region_write32(kmac->base_addr, KMAC_CMD_REG_OFFSET, cmd_reg);
819
820 // Reset operation state.
821 operation_state->squeezing = false;
822 operation_state->append_d = false;
823 operation_state->offset = 0;
824 operation_state->r = 0;
825 operation_state->d = 0;
826
827 return kDifOk;
828}
829
830dif_result_t dif_kmac_context_save(const dif_kmac_t *kmac,
831 dif_kmac_operation_state_t *operation_state,
832 dif_kmac_context_t *context) {
833 if (kmac == NULL || operation_state == NULL || context == NULL) {
834 return kDifBadArg;
835 }
836
837 // A context can only be saved while the message is absorbed.
838 if (operation_state->squeezing) {
839 return kDifError;
840 }
841
842 const mmio_region_t base = kmac->base_addr;
843
844 // Issue stop command and wait until the absorbing stage has been stopped.
845 uint32_t cmd_reg =
846 bitfield_field32_write(0, KMAC_CMD_CMD_FIELD, KMAC_CMD_CMD_VALUE_STOP);
847 mmio_region_write32(base, KMAC_CMD_REG_OFFSET, cmd_reg);
848
849 DIF_RETURN_IF_ERROR(dif_kmac_poll_status(kmac, KMAC_STATUS_SHA3_STOPPED_BIT));
850
851 for (size_t i = 0; i < kDifKmacStateWords; ++i) {
852 ptrdiff_t offset =
853 KMAC_STATE_REG_OFFSET + (ptrdiff_t)i * (ptrdiff_t)sizeof(uint32_t);
854 context->share0[i] = mmio_region_read32(base, offset);
855 context->share1[i] =
856 mmio_region_read32(base, offset + kDifKmacStateShareOffset);
857 }
858
859 context->operation_state = *operation_state;
860
861 cmd_reg =
862 bitfield_field32_write(0, KMAC_CMD_CMD_FIELD, KMAC_CMD_CMD_VALUE_DONE);
863 mmio_region_write32(base, KMAC_CMD_REG_OFFSET, cmd_reg);
864
865 // Reset operation state.
866 operation_state->squeezing = false;
867 operation_state->append_d = false;
868 operation_state->offset = 0;
869 operation_state->r = 0;
870 operation_state->d = 0;
871
872 return kDifOk;
873}
874
875dif_result_t dif_kmac_context_restore(
876 const dif_kmac_t *kmac, const dif_kmac_context_t *context,
877 dif_kmac_operation_state_t *operation_state) {
878 if (kmac == NULL || context == NULL || operation_state == NULL) {
879 return kDifBadArg;
880 }
881
882 // The keccak state is only writable while the hardware is idle.
883 if (!is_state_idle(kmac)) {
884 return kDifError;
885 }
886
887 const mmio_region_t base = kmac->base_addr;
888
889 uint32_t cmd_reg = bitfield_field32_write(0, KMAC_CMD_CMD_FIELD,
890 KMAC_CMD_CMD_VALUE_STATE_WRITE);
891 mmio_region_write32(base, KMAC_CMD_REG_OFFSET, cmd_reg);
892
893 // Wait until we have claimed the KMAC block. If an application interface
894 // was granted the block instead, an error is reported.
895 DIF_RETURN_IF_ERROR(dif_kmac_poll_status(kmac, KMAC_STATUS_STATE_WRITE_BIT));
896
897 for (size_t i = 0; i < kDifKmacStateWords; ++i) {
898 ptrdiff_t offset =
899 KMAC_STATE_REG_OFFSET + (ptrdiff_t)i * (ptrdiff_t)sizeof(uint32_t);
900 mmio_region_write32(base, offset, context->share0[i]);
901 mmio_region_write32(base, offset + kDifKmacStateShareOffset,
902 context->share1[i]);
903 }
904
905 // Issue continue command.
906 cmd_reg = bitfield_field32_write(0, KMAC_CMD_CMD_FIELD,
907 KMAC_CMD_CMD_VALUE_CONTINUE);
908 mmio_region_write32(base, KMAC_CMD_REG_OFFSET, cmd_reg);
909
910 *operation_state = context->operation_state;
911
912 return dif_kmac_poll_status(kmac, KMAC_STATUS_SHA3_ABSORB_BIT);
913}
914
915dif_result_t dif_kmac_context_release(const dif_kmac_t *kmac) {
916 if (kmac == NULL) {
917 return kDifBadArg;
918 }
919
920 uint32_t cmd_reg =
921 bitfield_field32_write(0, KMAC_CMD_CMD_FIELD, KMAC_CMD_CMD_VALUE_DONE);
922 mmio_region_write32(kmac->base_addr, KMAC_CMD_REG_OFFSET, cmd_reg);
923
924 return kDifOk;
925}
926
927dif_result_t dif_kmac_config_is_locked(const dif_kmac_t *kmac,
928 bool *is_locked) {
929 if (kmac == NULL || is_locked == NULL) {
930 return kDifBadArg;
931 }
932
933 *is_locked = !mmio_region_read32(kmac->base_addr, KMAC_CFG_REGWEN_REG_OFFSET);
934 return kDifOk;
935}
936
937dif_result_t dif_kmac_entropy_config_is_locked(const dif_kmac_t *kmac,
938 bool *is_locked) {
939 if (kmac == NULL || is_locked == NULL) {
940 return kDifBadArg;
941 }
942
943 *is_locked =
944 !mmio_region_read32(kmac->base_addr, KMAC_ENTROPY_CFG_REGWEN_REG_OFFSET);
945 return kDifOk;
946}
947
948dif_result_t dif_kmac_get_status(const dif_kmac_t *kmac,
949 dif_kmac_status_t *kmac_status) {
950 if (kmac == NULL || kmac_status == NULL) {
951 return kDifBadArg;
952 }
953
954 uint32_t reg = mmio_region_read32(kmac->base_addr, KMAC_STATUS_REG_OFFSET);
955
956 kmac_status->sha3_state = bitfield_field32_read(
957 reg,
958 (bitfield_field32_t){.mask = 0x0F, .index = KMAC_STATUS_SHA3_IDLE_BIT});
959
960 kmac_status->fifo_depth =
961 bitfield_field32_read(reg, KMAC_STATUS_FIFO_DEPTH_FIELD);
962
963 kmac_status->fifo_state = bitfield_field32_read(
964 reg,
965 (bitfield_field32_t){.mask = 0x03, .index = KMAC_STATUS_FIFO_EMPTY_BIT});
966
967 kmac_status->faults = bitfield_field32_read(
968 reg, (bitfield_field32_t){.mask = 0x03,
969 .index = KMAC_STATUS_ALERT_FATAL_FAULT_BIT});
970
971 return kDifOk;
972}
973
974dif_result_t dif_kmac_get_hash_counter(const dif_kmac_t *kmac,
975 uint32_t *hash_ctr) {
976 if (kmac == NULL || hash_ctr == NULL) {
977 return kDifBadArg;
978 }
979
980 uint32_t reg = mmio_region_read32(kmac->base_addr,
981 KMAC_ENTROPY_REFRESH_HASH_CNT_REG_OFFSET);
982
983 *hash_ctr =
984 bitfield_field32_read(reg, KMAC_ENTROPY_REFRESH_HASH_CNT_HASH_CNT_FIELD);
985
986 return kDifOk;
987}
988
989dif_result_t dif_kmac_get_error(const dif_kmac_t *kmac, dif_kmac_error_t *error,
990 uint32_t *info) {
991 if (kmac == NULL || error == NULL || info == NULL) {
992 return kDifBadArg;
993 }
994
995 uint32_t reg = mmio_region_read32(kmac->base_addr, KMAC_ERR_CODE_REG_OFFSET);
996 *info = reg & 0xFFFFFF;
997 *error = (reg >> 24) & 0xFF;
998 return kDifOk;
999}
1000
1001dif_result_t dif_kmac_reset(const dif_kmac_t *kmac,
1002 dif_kmac_operation_state_t *operation_state) {
1003 if (kmac == NULL || operation_state == NULL) {
1004 return kDifBadArg;
1005 }
1006 operation_state->d = 0;
1007 operation_state->r = 0;
1008 operation_state->offset = 0;
1009 operation_state->squeezing = false;
1010 DIF_RETURN_IF_ERROR(dif_kmac_err_processed(kmac));
1011 return kDifOk;
1012}
1013
1014dif_result_t dif_kmac_err_processed(const dif_kmac_t *kmac) {
1015 if (kmac == NULL) {
1016 return kDifBadArg;
1017 }
1018 uint32_t reg = 0;
1019 reg = bitfield_bit32_write(reg, KMAC_CMD_ERR_PROCESSED_BIT, 1);
1020 mmio_region_write32(kmac->base_addr, KMAC_CMD_REG_OFFSET, reg);
1021 return kDifOk;
1022}