Software APIs
dif_kmac.h
Go to the documentation of this file.
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#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_KMAC_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_KMAC_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/kmac/doc/">KMAC</a> Device Interface Functions
11 */
12
13#include <stdint.h>
14
18
19#include "sw/device/lib/dif/autogen/dif_kmac_autogen.h"
20
21#ifdef __cplusplus
22extern "C" {
23#endif // __cplusplus
24
25/**
26 * This API implements an interface for the KMAC hardware.
27 *
28 * The KMAC hardware implements the following cryptographic hash and message
29 * authentication code (MAC) functions:
30 *
31 * - SHA-3 [1]
32 * - SHAKE [1]
33 * - cSHAKE [2]
34 * - KMAC [2]
35 *
36 * The following sequence of operations is required to initialize the KMAC
37 * hardware:
38 *
39 * - `dif_kmac_init()`
40 * - `dif_kmac_configure()`
41 *
42 * If configuration changes are required then `dif_kmac_configure` can be called
43 * again so long as there are no operations in progress.
44 *
45 * The following sequence of operations is required to execute an operation:
46 *
47 * - `dif_kmac_{sha3,shake,cshake,kmac}_start()`
48 * - `dif_kmac_absorb()`
49 * - `dif_kmac_squeeze()`
50 * - `dif_kmac_end()`
51 *
52 * This is a streaming API and the `dif_kmac_absorb` and `dif_kmac_squeeze`
53 * functions may be called multiple times during a single operation. Once
54 * `dif_kmac_squeeze` has been called however no further `dif_kmac_absorb` calls
55 * may be made. See NIST FIPS 202 [1] for more information about the sponge
56 * construction and the 'absorbing' and 'squeezing' states.
57 *
58 * Please see the following documentation for more information about the KMAC
59 * hardware:
60 * https://docs.opentitan.org/hw/ip/kmac/doc/
61 *
62 * References:
63 * [1] - NIST FIPS 202
64 * SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions
65 * http://dx.doi.org/10.6028/NIST.FIPS.202
66 * [2] - NIST Special Publication 800-185
67 * SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash and ParallelHash
68 * https://doi.org/10.6028/NIST.SP.800-185
69 */
70
71/**
72 * Supported entropy modes.
73 *
74 * Entropy may be provided by the entropy distribution network (EDN) or using a
75 * seed provided by software.
76 */
78 kDifKmacEntropyModeIdle = 0,
79 kDifKmacEntropyModeEdn,
80 kDifKmacEntropyModeSoftware,
82
83/**
84 * Maximum lengths supported by the KMAC unit.
85 */
86enum {
87
88 /**
89 * The maximum length in bytes of a customization string (S) before it has
90 * been encoded.
91 */
93
94 /**
95 * The maximum number of bytes required to encode the length of the
96 * customization string.
97 *
98 * Assumes maximum customization string length of 32 bytes (256 bits).
99 */
101
102 /**
103 * The maximum length in bytes of a function name (N) before it has been
104 * encoded.
105 */
107
108 /**
109 * The maximum number of bytes required to encode the length of the function
110 * name.
111 *
112 * Assumes maximum function name length of 4 bytes (32 bits).
113 */
115
116 /**
117 * The maximum output length (L) that can be set when starting a KMAC
118 * operation.
119 *
120 * The length is in 32-bit words and is designed to be low enough that the
121 * length in bits can still be represented by an unsigned 32-bit integer.
122 */
123 kDifKmacMaxOutputLenWords = (UINT32_MAX - 32) / 32,
124
125 /**
126 * The maximum key length supported by the KMAC operation.
127 *
128 * The length is in 32-bit words.
129 */
131
132 /**
133 * The length of the software entropy seed.
134 *
135 * The length is in 32-bit words.
136 */
138 /**
139 * The offset of the second share within the output state register.
140 */
142 /**
143 * The size of the Keccak state in words (i.e. 1600 bits).
144 */
145 kDifKmacStateWords = 1600 / 8 / sizeof(uint32_t),
146};
147
148/**
149 * Runtime configuration for KMAC.
150 *
151 * This struct describes runtime information for configuration of the hardware.
152 */
153typedef struct dif_kmac_config {
154 /**
155 * Entropy mode specifying the source of entropy (EDN or software).
156 */
158
159 /**
160 * Entropy fast process mode when enabled prevents the KMAC unit consuming
161 * entropy unless it is processing a secret key. This process should not be
162 * used when resistance against side-channel attacks is required, because
163 * it may lead to leakage of the secret key in the power trace.
164 */
166
167 /**
168 * Entropy seed. Only used when the source of entropy is software.
169 */
171
172 /**
173 * The number of KMAC invocations that triggers an automatic seed request from
174 * EDN.
175 */
177
178 /**
179 * Number of clock cycles to wait for the EDN to reseed the entropy generator
180 * before an error is raised (see `dif_kmac_get_error`). If 0 the unit will
181 * wait forever.
182 */
184
185 /**
186 * Prescaler value that determines how many clock pulse triggers an increment
187 * in the timer counter.
188 */
190
191 /**
192 * Convert the message to big-endian byte order.
193 * Note: this option currently had no effect since the message is sent a byte
194 * at a time but will in the future.
195 */
197
198 /**
199 * Convert the output state (digest) to big-endian byte order on a word
200 * granularity.
201 */
203
204 /**
205 * Place kmac inside key sideload mode
206 */
208
209 /**
210 * Message Masking with PRNG.
211 * If true, KMAC applies PRNG to the input messages to the Keccak module when
212 * KMAC mode is on.
213 */
215
217
218/**
219 * A KMAC operation state context.
220 */
222 /**
223 * Whether the 'squeezing' phase has been started.
224 */
226
227 /**
228 * Flag indicating whether the output length (d) should be right encoded in
229 * software and appended to the end of the message. The output length is
230 * required to be appended to the message as part of a KMAC operation.
231 */
233
234 /**
235 * Offset into the output state.
236 */
237 size_t offset;
238
239 /**
240 * The rate (r) in 32-bit words.
241 */
242 size_t r;
243
244 /**
245 * The output length (d) in 32-bit words.
246 *
247 * If the output length is not fixed then this field will be set to 0.
248 *
249 * Note: if the output length is fixed length will be modified to ensure that
250 * `d - offset` always accurately reflects the number of words remaining.
251 */
252 size_t d;
254
255/**
256 * Supported SHA-3 modes of operation.
257 */
258typedef enum dif_kmac_mode_sha3 {
259 /** SHA-3 with 224 bit strength. */
261 /** SHA-3 with 256 bit strength. */
263 /** SHA-3 with 384 bit strength. */
265 /** SHA-3 with 512 bit strength. */
268
269/**
270 * Supported SHAKE modes of operation.
271 */
273 /** SHAKE with 128 bit strength. */
275 /** SHAKE with 256 bit strength. */
278
279/**
280 * Supported cSHAKE modes of operation.
281 */
283 /** cSHAKE with 128 bit strength. */
285 /** cSHAKE with 256 bit strength. */
288
289/**
290 * Supported KMAC modes of operation.
291 */
292typedef enum dif_kmac_mode_kmac {
293 /** KMAC with 128 bit strength. */
295 /** KMAC with 256 bit strength. */
298
299/**
300 * Key length.
301 *
302 * The key length is specified in bits.
303 */
305 /** Software provided 128 bit key. */
307 /** Software provided 192 bit key. */
309 /** Software provided 256 bit key. */
311 /** Software provided 384 bit key. */
313 /** Software provided 512 bit key. */
316
317/**
318 * A key for KMAC operations.
319 *
320 * The key is provided in two parts, `share0` and `share1`. These are
321 * combined using a bitwise XOR operation in the KMAC unit to produce the real
322 * key.
323 *
324 * The key shares are encoded in little endian byte order. This is fixed and
325 * cannot be changed (unlike the byte order used for the message and state).
326 *
327 * Unused words in the key shares must be set to 0.
328 */
329typedef struct dif_kmac_key {
330 uint32_t share0[kDifKmacMaxKeyLenWords];
331 uint32_t share1[kDifKmacMaxKeyLenWords];
334
335/**
336 * An encoded bit string used for customization string (S).
337 *
338 * Use `dif_kmac_customization_string_init` to initialize.
339 */
341 /** Encoded S: left_encode(len(S)) || S */
344 /** Length of data in buffer in bytes. */
345 uint32_t length;
347
348/**
349 * An encoded bit string used for function name (N).
350 *
351 * Use `dif_kmac_function_name_init` to initialize.
352 */
354 /** Encoded N: left_encode(len(N)) || N */
356 /** Length of data in buffer in bytes. */
357 uint32_t length;
359
360/**
361 * Error reported by KMAC unit.
362 *
363 * Codes taken from hw/ip/kmac/rtl/kmac_pkg.sv:err_code_e
364 */
365typedef enum dif_kmac_error {
366 /**
367 * No error has occured.
368 */
370
371 /**
372 * The Key Manager has raised an error because the secret key is not valid.
373 */
375
376 /**
377 * An attempt was made to write data into the message FIFO but the KMAC unit
378 * was not in the correct state to receive the data.
379 */
381
382 /**
383 * SW issued a command while a HW application interface was using KMAC.
384 */
386
387 /**
388 * The entropy wait timer has expired.
389 */
391
392 /**
393 * Incorrect entropy mode when entropy is ready.
394 */
396
397 kDifErrorUnexpectedModeStrength = 6,
398
399 kDifErrorIncorrectFunctionName = 7,
400
401 kDifErrorSoftwareCommandSequence = 8,
402
403 kDifErrorSoftwareHashingWithoutEntropyReady = 9,
404
405 kDifErrorFatalError = 0xC1,
406
407 kDifErrorPackerIntegrity = 0xC2,
408
409 kDifErrorMsgFifoIntegrity = 0xC3,
411
412/**
413 * The state of the message FIFO used to buffer absorbed data.
414 *
415 * The hardware defined these status in different bit fields, however they work
416 * better in the same field. i.e the fifo can't be empty and full at the same
417 * time. That said, the values chosen for this enum allow the conversion from
418 * the register bits to this enum without branches.
419 */
421 /** The message FIFO is not empty or full. */
423 /** The message FIFO is empty. */
425 /** The message FIFO is full. Further writes will block. */
428
430 /**
431 * SHA3 hashing engine is in idle state.
432 */
434
435 /**
436 * SHA3 is receiving message stream and processing it.
437 */
439
440 /**
441 * SHA3 completes sponge absorbing stage. In this stage, SW can manually run
442 * the hashing engine.
443 */
445} dif_kmac_sha3_state_t;
446
447/**
448 * The kmac error faults.
449 *
450 * The hardware defined these status in different bit fields, however they work
451 * better in the same field. Then the values chosen for this enum allow the
452 * conversion from the register bits to this enum without branches.
453 */
455 /**
456 * Neither errors nor fault has occurred.
457 */
459 /**
460 * A fatal fault has occurred and the KMAC unit needs to be reset (1),
461 * Examples for such faults include i) TL-UL bus integrity fault ii)
462 * storage errors in the shadow registers iii) errors in the message,
463 * round, or key counter iv) any internal FSM entering an invalid state v)
464 * an error in the redundant lfsr.
465 */
467 /**
468 * An update error has occurred in the shadowed Control Register. KMAC
469 * operation needs to be restarted by re-writing the Control Register.
470 */
473
474typedef struct dif_kmac_status {
475 /**
476 * Sha3 state.
477 */
478 dif_kmac_sha3_state_t sha3_state;
479
480 /**
481 * Message FIFO entry count.
482 */
483 uint32_t fifo_depth;
484
485 /**
486 * Kmac fifo state.
487 */
489
490 /**
491 * Kmac faults and errors state.
492 */
494} dif_kmac_status_t;
495
496/**
497 * Configures KMAC with runtime information.
498 *
499 * @param kmac A KMAC handle.
500 * @param config Runtime configuration parameters.
501 * @return The result of the operation.
502 */
505
506/**
507 * Encode a customization string (S).
508 *
509 * The length of the string must not exceed `kDifKmacMaxCustomizationStringLen`.
510 *
511 * Note that this function will encode `len` bytes from `data` regardless of
512 * whether `data` is null-terminated or not.
513 *
514 * See NIST Special Publication 800-185 [2] for more information about the
515 * customization string (S) parameter.
516 *
517 * @param data String to encode.
518 * @param len Length of string to encode.
519 * @param[out] out Encoded customization string.
520 * @return The result of the operation.
521 */
524 const char *data, size_t len, dif_kmac_customization_string_t *out);
525
526/**
527 * Encode a function name (N).
528 *
529 * The length of the string must not exceed `kDifKmacMaxFunctionNameLen`.
530 *
531 * Note that this function will encode `len` bytes from `data` regardless of
532 * whether `data` is null-terminated or not.
533 *
534 * See NIST Special Publication 800-185 [2] for more information about the
535 * function name (N) parameter.
536 *
537 * @param data String to encode.
538 * @param len Length of string to encode.
539 * @param[out] out Encoded function name.
540 * @return The result of the operation.
541 */
543dif_result_t dif_kmac_function_name_init(const char *data, size_t len,
545
546/**
547 * Start a SHA-3 operation.
548 *
549 * SHA-3 operations have a fixed output length.
550 *
551 * See NIST FIPS 202 [1] for more information about SHA-3.
552 *
553 * @param kmac A KMAC handle.
554 * @param operation_state A KMAC operation state context.
555 * @param mode The SHA-3 mode of operation.
556 * @return The result of the operation.
557 */
560 const dif_kmac_t *kmac, dif_kmac_operation_state_t *operation_state,
562
563/**
564 * Start a SHAKE operation.
565 *
566 * SHAKE operations have a variable (XOF) output length.
567 *
568 * See NIST FIPS 202 [1] for more information about SHAKE.
569 *
570 * @param kmac A KMAC handle.
571 * @param operation_state A KMAC operation state context.
572 * @param mode The mode of operation.
573 * @return The result of the operation.
574 */
577 const dif_kmac_t *kmac, dif_kmac_operation_state_t *operation_state,
579
580/**
581 * Start a cSHAKE operation.
582 *
583 * cSHAKE operations have a variable (XOF) output length.
584 *
585 * See NIST Special Publication 800-185 [2] for more information about cSHAKE.
586 *
587 * @param kmac A KMAC handle.
588 * @param operation_state A KMAC operation state context.
589 * @param mode The mode of operation.
590 * @param n Function name (optional).
591 * @param s Customization string (optional).
592 * @return The result of the operation.
593 */
596 const dif_kmac_t *kmac, dif_kmac_operation_state_t *operation_state,
599
600/**
601 * Start a KMAC operation.
602 *
603 * To use KMAC in eXtendable-Output Function (XOF) mode set the output length
604 * (`l`) to 0. The output length must not be greater than
605 * `kDifKmacMaxOutputLenWords`.
606 *
607 * The key provided must have at least as many bits as the security strength
608 * of the `mode`.
609 *
610 * See NIST Special Publication 800-185 [2] for more information about KMAC.
611 *
612 * @param kmac A KMAC handle.
613 * @param operation_state A KMAC operation state context.
614 * @param mode The mode of operation.
615 * @param l Output length (number of 32-bit words that will be 'squeezed').
616 * @param k Pointer to secret key.
617 * @param s Customization string (optional).
618 * @return The result of the operation.
619 */
622 const dif_kmac_t *kmac, dif_kmac_operation_state_t *operation_state,
623 dif_kmac_mode_kmac_t mode, size_t l, const dif_kmac_key_t *k,
625
626/**
627 * Absorb bytes from the message provided.
628 *
629 * If `processed` is non-NULL, then this function will write the remaining
630 * space in the FIFO and update `processed` with the number of bytes written.
631 * The caller should adjust the `msg` pointer and `len` parameters and call
632 * again as needed until all input has been written.
633 *
634 * If `processed` is NULL, then this function will block until the entire
635 * message has been processed or an error occurs.
636 *
637 * If big-endian mode is enabled for messages (`message_big_endian`) only the
638 * part of the message aligned to 32-bit word boundaries will be byte swapped.
639 * Unaligned leading and trailing bytes will be written into the message as-is.
640 *
641 * @param kmac A KMAC handle.
642 * @param operation_state A KMAC operation state context.
643 * @param msg Pointer to data to absorb.
644 * @param len Number of bytes of data to absorb.
645 * @param[out] processed Number of bytes processed (optional).
646 * @preturn The result of the operation.
647 */
650 dif_kmac_operation_state_t *operation_state,
651 const void *msg, size_t len, size_t *processed);
652
653/**
654 * Squeeze bytes into the output buffer provided.
655 *
656 * Requesting a squeeze operation will prevent any further absorption operations
657 * from taking place.
658 *
659 * If `kDifKmacIncomplete` is returned then the hardware is currently
660 * recomputing the state and the output was only partially written. The output
661 * pointer and length should be updated according to the number of bytes
662 * processed and the squeeze operation continued at a later time.
663 *
664 * If `processed` is not provided then this function will block until `len`
665 * bytes have been written to `out` or an error occurs.
666 *
667 * Normally, the capacity part of Keccak state is and should not be read
668 * as part of a regular cryptographic operation. However, this function
669 * can also read the capacity for testing purposes.
670 * When `capacity` is a non-NULL pointer, at the end of the operation, the
671 * capacity part of the Keccak state is also read and written into this buffer.
672 * The capacity is read for each output round, meaning that if the requested
673 * digest is larger than a single Keccak round can provide (i.e. the rate), then
674 * the additional rounds also update this buffer. Hence it should be large
675 * enough to accommodate `ceil(digest_len/rate_len) * capacity_len`.
676 * `capacity` can be set to NULL to skip reading the capacity.
677 *
678 * @param kmac A KMAC handle.
679 * @param operation_state A KMAC operation state context.
680 * @param[out] out Pointer to output buffer.
681 * @param[out] len Number of 32-bit words to write to output buffer.
682 * @param[out] processed Number of 32-bit words written to output buffer
683 * (optional).
684 * @param[out] capacity Optional buffer to read capacity along with the digest.
685 * @preturn The result of the operation.
686 */
689 dif_kmac_operation_state_t *operation_state,
690 uint32_t *out, size_t len, size_t *processed,
691 uint32_t *capacity);
692
693/**
694 * Ends a squeeze operation and resets the hardware so it is ready for a new
695 * operation.
696 *
697 * @param kmac A KMAC handle.
698 * @param operation_state A KMAC operation state context.
699 * @return The result of the operation.
700 */
703 dif_kmac_operation_state_t *operation_state);
704
705/**
706 * Read the kmac error register to get the error code indicated the interrupt
707 * state.
708 *
709 * This function should be called in case of any of the `start` functions
710 * returns `kDifError`.
711 *
712 * @param kmac A KMAC handle.
713 * @param[out] error The current error code.
714 * @param[out] info Optional additional error information.
715 * @return The result of the operation.
716 */
719 uint32_t *info);
720
721/**
722 * Clear the current error code and reset the state machine to the idle state
723 * ready to accept new operations.
724 *
725 * The state of any in-progress operation will be lost and the operation will
726 * need to be restarted.
727 *
728 * @param kmac A KMAC handle.
729 * @param operation_state A KMAC operation state context.
730 * @return The result of the operation.
731 */
734 dif_kmac_operation_state_t *operation_state);
735
736/**
737 * Let the KMAC HW know that SW has processed the errors the HW has flagged.
738 *
739 * @param kmac A KMAC handle
740 * @return The result of the operation.
741 */
744
745/**
746 * Report whether the hardware currently indicates an error.
747 *
748 * @param kmac A KMAC handle.
749 * @param[out] error Whether hardware currently indicates an error.
750 * @returns The result of the operation.
751 */
753dif_result_t dif_kmac_has_error_occurred(const dif_kmac_t *kmac, bool *error);
754
755/**
756 * Clear the `kmac_err` IRQ.
757 *
758 * @param kmac A KMAC handle.
759 * @return The result of the operation.
760 */
763
764/**
765 * Fetch the current status of the message FIFO used to buffer absorbed data.
766 *
767 * @param kmac A KMAC handle.
768 * @param[out] kmac_status The kmac status struct.
769 * @return The result of the operation.
770 */
773 dif_kmac_status_t *kmac_status);
774
775/**
776 * Returns the current value of the refresh hash counter.
777 *
778 * @param kmac A KMAC handle.
779 * @param hash_ctr The hash counter value that is returned.
780 * @return The result of the operation.
781 */
784 uint32_t *hash_ctr);
785
786/**
787 * Reports whether or not the KMAC configuration register is locked.
788 *
789 * If writes to the KMAC configuration register are disabled (locked) then it is
790 * not possible to change any configuration parameters or start a new operation.
791 * The configuration register is locked when an operation has been started and
792 * is unlocked again when it completes.
793 *
794 * @param kmac A KMAC handle.
795 * @param[out] is_locked Out-param reporting the lock state.
796 * @return The result of the operation.
797 */
799dif_result_t dif_kmac_config_is_locked(const dif_kmac_t *kmac, bool *is_locked);
800
801/**
802 * Poll until a given flag in the status register is set.
803 *
804 * @param kmac A KMAC handle.
805 * @param flag the
806 * @return The result of the operation.
807 */
809dif_result_t dif_kmac_poll_status(const dif_kmac_t *kmac, uint32_t flag);
810
811#ifdef __cplusplus
812} // extern "C"
813#endif // __cplusplus
814
815#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_KMAC_H_