Software APIs
sw
device
lib
dif
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
15
#include "
sw/device/lib/base/macros.h
"
16
#include "
sw/device/lib/base/mmio.h
"
17
#include "
sw/device/lib/dif/dif_base.h
"
18
19
#include "
sw/device/lib/dif/autogen/dif_kmac_autogen.h
"
20
21
#ifdef __cplusplus
22
extern
"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
*/
77
typedef
enum
dif_kmac_entropy_mode
{
78
kDifKmacEntropyModeIdle = 0,
79
kDifKmacEntropyModeEdn,
80
kDifKmacEntropyModeSoftware,
81
}
dif_kmac_entropy_mode_t
;
82
83
/**
84
* Maximum lengths supported by the KMAC unit.
85
*/
86
enum
{
87
88
/**
89
* The maximum length in bytes of a customization string (S) before it has
90
* been encoded.
91
*/
92
kDifKmacMaxCustomizationStringLen
= 32,
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
*/
100
kDifKmacMaxCustomizationStringOverhead
= 3,
101
102
/**
103
* The maximum length in bytes of a function name (N) before it has been
104
* encoded.
105
*/
106
kDifKmacMaxFunctionNameLen
= 4,
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
*/
114
kDifKmacMaxFunctionNameOverhead
= 2,
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
*/
130
kDifKmacMaxKeyLenWords
= 512 / 32,
131
132
/**
133
* The length of the software entropy seed.
134
*
135
* The length is in 32-bit words.
136
*/
137
kDifKmacEntropySeedWords
= 6,
138
/**
139
* The offset of the second share within the output state register.
140
*/
141
kDifKmacStateShareOffset
= 0x100,
142
};
143
144
/**
145
* Runtime configuration for KMAC.
146
*
147
* This struct describes runtime information for configuration of the hardware.
148
*/
149
typedef
struct
dif_kmac_config
{
150
/**
151
* Entropy mode specifying the source of entropy (EDN or software).
152
*/
153
dif_kmac_entropy_mode_t
entropy_mode
;
154
155
/**
156
* Entropy fast process mode when enabled prevents the KMAC unit consuming
157
* entropy unless it is processing a secret key. This process should not be
158
* used when resistance against side-channel attacks is required, because
159
* it may lead to leakage of the secret key in the power trace.
160
*/
161
bool
entropy_fast_process
;
162
163
/**
164
* Entropy seed. Only used when the source of entropy is software.
165
*/
166
uint32_t
entropy_seed
[
kDifKmacEntropySeedWords
];
167
168
/**
169
* The number of KMAC invocations that triggers an automatic seed request from
170
* EDN.
171
*/
172
uint16_t
entropy_hash_threshold
;
173
174
/**
175
* Number of clock cycles to wait for the EDN to reseed the entropy generator
176
* before an error is raised (see `dif_kmac_get_error`). If 0 the unit will
177
* wait forever.
178
*/
179
uint16_t
entropy_wait_timer
;
180
181
/**
182
* Prescaler value that determines how many clock pulse triggers an increment
183
* in the timer counter.
184
*/
185
uint16_t
entropy_prescaler
;
186
187
/**
188
* Convert the message to big-endian byte order.
189
* Note: this option currently had no effect since the message is sent a byte
190
* at a time but will in the future.
191
*/
192
bool
message_big_endian
;
193
194
/**
195
* Convert the output state (digest) to big-endian byte order on a word
196
* granularity.
197
*/
198
bool
output_big_endian
;
199
200
/**
201
* Place kmac inside key sideload mode
202
*/
203
bool
sideload
;
204
205
/**
206
* Message Masking with PRNG.
207
* If true, KMAC applies PRNG to the input messages to the Keccak module when
208
* KMAC mode is on.
209
*/
210
bool
msg_mask
;
211
212
}
dif_kmac_config_t
;
213
214
/**
215
* A KMAC operation state context.
216
*/
217
typedef
struct
dif_kmac_operation_state
{
218
/**
219
* Whether the 'squeezing' phase has been started.
220
*/
221
bool
squeezing
;
222
223
/**
224
* Flag indicating whether the output length (d) should be right encoded in
225
* software and appended to the end of the message. The output length is
226
* required to be appended to the message as part of a KMAC operation.
227
*/
228
bool
append_d
;
229
230
/**
231
* Offset into the output state.
232
*/
233
size_t
offset
;
234
235
/**
236
* The rate (r) in 32-bit words.
237
*/
238
size_t
r
;
239
240
/**
241
* The output length (d) in 32-bit words.
242
*
243
* If the output length is not fixed then this field will be set to 0.
244
*
245
* Note: if the output length is fixed length will be modified to ensure that
246
* `d - offset` always accurately reflects the number of words remaining.
247
*/
248
size_t
d
;
249
}
dif_kmac_operation_state_t
;
250
251
/**
252
* Supported SHA-3 modes of operation.
253
*/
254
typedef
enum
dif_kmac_mode_sha3
{
255
/** SHA-3 with 224 bit strength. */
256
kDifKmacModeSha3Len224
,
257
/** SHA-3 with 256 bit strength. */
258
kDifKmacModeSha3Len256
,
259
/** SHA-3 with 384 bit strength. */
260
kDifKmacModeSha3Len384
,
261
/** SHA-3 with 512 bit strength. */
262
kDifKmacModeSha3Len512
,
263
}
dif_kmac_mode_sha3_t
;
264
265
/**
266
* Supported SHAKE modes of operation.
267
*/
268
typedef
enum
dif_kmac_mode_shake
{
269
/** SHAKE with 128 bit strength. */
270
kDifKmacModeShakeLen128
,
271
/** SHAKE with 256 bit strength. */
272
kDifKmacModeShakeLen256
,
273
}
dif_kmac_mode_shake_t
;
274
275
/**
276
* Supported cSHAKE modes of operation.
277
*/
278
typedef
enum
dif_kmac_mode_cshake
{
279
/** cSHAKE with 128 bit strength. */
280
kDifKmacModeCshakeLen128
,
281
/** cSHAKE with 256 bit strength. */
282
kDifKmacModeCshakeLen256
,
283
}
dif_kmac_mode_cshake_t
;
284
285
/**
286
* Supported KMAC modes of operation.
287
*/
288
typedef
enum
dif_kmac_mode_kmac
{
289
/** KMAC with 128 bit strength. */
290
kDifKmacModeKmacLen128
,
291
/** KMAC with 256 bit strength. */
292
kDifKmacModeKmacLen256
,
293
}
dif_kmac_mode_kmac_t
;
294
295
/**
296
* Key length.
297
*
298
* The key length is specified in bits.
299
*/
300
typedef
enum
dif_kmac_key_length
{
301
/** Software provided 128 bit key. */
302
kDifKmacKeyLen128
= 0,
303
/** Software provided 192 bit key. */
304
kDifKmacKeyLen192
= 1,
305
/** Software provided 256 bit key. */
306
kDifKmacKeyLen256
= 2,
307
/** Software provided 384 bit key. */
308
kDifKmacKeyLen384
= 3,
309
/** Software provided 512 bit key. */
310
kDifKmacKeyLen512
= 4,
311
}
dif_kmac_key_length_t
;
312
313
/**
314
* A key for KMAC operations.
315
*
316
* The key is provided in two parts, `share0` and `share1`. These are
317
* combined using a bitwise XOR operation in the KMAC unit to produce the real
318
* key.
319
*
320
* The key shares are encoded in little endian byte order. This is fixed and
321
* cannot be changed (unlike the byte order used for the message and state).
322
*
323
* Unused words in the key shares must be set to 0.
324
*/
325
typedef
struct
dif_kmac_key
{
326
uint32_t share0[
kDifKmacMaxKeyLenWords
];
327
uint32_t share1[
kDifKmacMaxKeyLenWords
];
328
dif_kmac_key_length_t
length;
329
}
dif_kmac_key_t
;
330
331
/**
332
* An encoded bit string used for customization string (S).
333
*
334
* Use `dif_kmac_customization_string_init` to initialize.
335
*/
336
typedef
struct
dif_kmac_customization_string
{
337
/** Encoded S: left_encode(len(S)) || S */
338
char
buffer
[
kDifKmacMaxCustomizationStringLen
+
339
kDifKmacMaxCustomizationStringOverhead
];
340
/** Length of data in buffer in bytes. */
341
uint32_t
length
;
342
}
dif_kmac_customization_string_t
;
343
344
/**
345
* An encoded bit string used for function name (N).
346
*
347
* Use `dif_kmac_function_name_init` to initialize.
348
*/
349
typedef
struct
dif_kmac_function_name
{
350
/** Encoded N: left_encode(len(N)) || N */
351
char
buffer
[
kDifKmacMaxFunctionNameLen
+
kDifKmacMaxFunctionNameOverhead
];
352
/** Length of data in buffer in bytes. */
353
uint32_t
length
;
354
}
dif_kmac_function_name_t
;
355
356
/**
357
* Error reported by KMAC unit.
358
*
359
* Codes taken from hw/ip/kmac/rtl/kmac_pkg.sv:err_code_e
360
*/
361
typedef
enum
dif_kmac_error
{
362
/**
363
* No error has occured.
364
*/
365
kDifErrorNone
,
366
367
/**
368
* The Key Manager has raised an error because the secret key is not valid.
369
*/
370
kDifErrorKeyNotValid
,
371
372
/**
373
* An attempt was made to write data into the message FIFO but the KMAC unit
374
* was not in the correct state to receive the data.
375
*/
376
kDifErrorSoftwarePushedMessageFifo
,
377
378
/**
379
* An invalid state transition was attempted (e.g. idle -> run without
380
* intermediate process state).
381
*/
382
kDifErrorSoftwarePushedWrongCommand
,
383
384
/**
385
* The entropy wait timer has expired.
386
*/
387
kDifErrorEntropyWaitTimerExpired
= 0x04000000,
388
389
/**
390
* Incorrect entropy mode when entropy is ready.
391
*/
392
kDifErrorEntropyModeIncorrect
,
393
394
/**
395
* An error was encountered but the cause is unknown.
396
*/
397
kDifErrorUnknownError
,
398
}
dif_kmac_error_t
;
399
400
/**
401
* The state of the message FIFO used to buffer absorbed data.
402
*
403
* The hardware defined these status in different bit fields, however they work
404
* better in the same field. i.e the fifo can't be empty and full at the same
405
* time. That said, the values chosen for this enum allow the conversion from
406
* the register bits to this enum without branches.
407
*/
408
typedef
enum
dif_kmac_fifo_state
{
409
/** The message FIFO is not empty or full. */
410
kDifKmacFifoStatePartial
= 0,
411
/** The message FIFO is empty. */
412
kDifKmacFifoStateEmpty
= 1 << 0,
413
/** The message FIFO is full. Further writes will block. */
414
kDifKmacFifoStateFull
= 1 << 1,
415
}
dif_kmac_fifo_state_t
;
416
417
typedef
enum
dif_kmac_sha3_state
{
418
/**
419
* SHA3 hashing engine is in idle state.
420
*/
421
kDifKmacSha3StateIdle
= 1 << 0,
422
423
/**
424
* SHA3 is receiving message stream and processing it.
425
*/
426
kDifKmacSha3StateAbsorbing
= 1 << 1,
427
428
/**
429
* SHA3 completes sponge absorbing stage. In this stage, SW can manually run
430
* the hashing engine.
431
*/
432
kDifKmacSha3StateSqueezing
= 1 << 2,
433
} dif_kmac_sha3_state_t;
434
435
/**
436
* The kmac error faults.
437
*
438
* The hardware defined these status in different bit fields, however they work
439
* better in the same field. Then the values chosen for this enum allow the
440
* conversion from the register bits to this enum without branches.
441
*/
442
typedef
enum
dif_kmac_alert_faults
{
443
/**
444
* Neither errors nor fault has occurred.
445
*/
446
kDifKmacAlertNone
= 0,
447
/**
448
* A fatal fault has occurred and the KMAC unit needs to be reset (1),
449
* Examples for such faults include i) TL-UL bus integrity fault ii)
450
* storage errors in the shadow registers iii) errors in the message,
451
* round, or key counter iv) any internal FSM entering an invalid state v)
452
* an error in the redundant lfsr.
453
*/
454
kDifKmacAlertFatalFault
= 1 << 0,
455
/**
456
* An update error has occurred in the shadowed Control Register. KMAC
457
* operation needs to be restarted by re-writing the Control Register.
458
*/
459
kDifKmacAlertRecovCtrlUpdate
= 1 << 1,
460
}
dif_kmac_alert_faults_t
;
461
462
typedef
struct
dif_kmac_status
{
463
/**
464
* Sha3 state.
465
*/
466
dif_kmac_sha3_state_t
sha3_state
;
467
468
/**
469
* Message FIFO entry count.
470
*/
471
uint32_t
fifo_depth
;
472
473
/**
474
* Kmac fifo state.
475
*/
476
dif_kmac_fifo_state_t
fifo_state
;
477
478
/**
479
* Kmac faults and errors state.
480
*/
481
dif_kmac_alert_faults_t
faults
;
482
}
dif_kmac_status_t
;
483
484
/**
485
* Configures KMAC with runtime information.
486
*
487
* @param kmac A KMAC handle.
488
* @param config Runtime configuration parameters.
489
* @return The result of the operation.
490
*/
491
OT_WARN_UNUSED_RESULT
492
dif_result_t
dif_kmac_configure
(
dif_kmac_t
*kmac,
dif_kmac_config_t
config);
493
494
/**
495
* Encode a customization string (S).
496
*
497
* The length of the string must not exceed `kDifKmacMaxCustomizationStringLen`.
498
*
499
* Note that this function will encode `len` bytes from `data` regardless of
500
* whether `data` is null-terminated or not.
501
*
502
* See NIST Special Publication 800-185 [2] for more information about the
503
* customization string (S) parameter.
504
*
505
* @param data String to encode.
506
* @param len Length of string to encode.
507
* @param[out] out Encoded customization string.
508
* @return The result of the operation.
509
*/
510
OT_WARN_UNUSED_RESULT
511
dif_result_t
dif_kmac_customization_string_init
(
512
const
char
*data,
size_t
len,
dif_kmac_customization_string_t
*out);
513
514
/**
515
* Encode a function name (N).
516
*
517
* The length of the string must not exceed `kDifKmacMaxFunctionNameLen`.
518
*
519
* Note that this function will encode `len` bytes from `data` regardless of
520
* whether `data` is null-terminated or not.
521
*
522
* See NIST Special Publication 800-185 [2] for more information about the
523
* function name (N) parameter.
524
*
525
* @param data String to encode.
526
* @param len Length of string to encode.
527
* @param[out] out Encoded function name.
528
* @return The result of the operation.
529
*/
530
OT_WARN_UNUSED_RESULT
531
dif_result_t
dif_kmac_function_name_init
(
const
char
*data,
size_t
len,
532
dif_kmac_function_name_t
*out);
533
534
/**
535
* Start a SHA-3 operation.
536
*
537
* SHA-3 operations have a fixed output length.
538
*
539
* See NIST FIPS 202 [1] for more information about SHA-3.
540
*
541
* @param kmac A KMAC handle.
542
* @param operation_state A KMAC operation state context.
543
* @param mode The SHA-3 mode of operation.
544
* @return The result of the operation.
545
*/
546
OT_WARN_UNUSED_RESULT
547
dif_result_t
dif_kmac_mode_sha3_start
(
548
const
dif_kmac_t
*kmac,
dif_kmac_operation_state_t
*operation_state,
549
dif_kmac_mode_sha3_t
mode);
550
551
/**
552
* Start a SHAKE operation.
553
*
554
* SHAKE operations have a variable (XOF) output length.
555
*
556
* See NIST FIPS 202 [1] for more information about SHAKE.
557
*
558
* @param kmac A KMAC handle.
559
* @param operation_state A KMAC operation state context.
560
* @param mode The mode of operation.
561
* @return The result of the operation.
562
*/
563
OT_WARN_UNUSED_RESULT
564
dif_result_t
dif_kmac_mode_shake_start
(
565
const
dif_kmac_t
*kmac,
dif_kmac_operation_state_t
*operation_state,
566
dif_kmac_mode_shake_t
mode);
567
568
/**
569
* Start a cSHAKE operation.
570
*
571
* cSHAKE operations have a variable (XOF) output length.
572
*
573
* See NIST Special Publication 800-185 [2] for more information about cSHAKE.
574
*
575
* @param kmac A KMAC handle.
576
* @param operation_state A KMAC operation state context.
577
* @param mode The mode of operation.
578
* @param n Function name (optional).
579
* @param s Customization string (optional).
580
* @return The result of the operation.
581
*/
582
OT_WARN_UNUSED_RESULT
583
dif_result_t
dif_kmac_mode_cshake_start
(
584
const
dif_kmac_t
*kmac,
dif_kmac_operation_state_t
*operation_state,
585
dif_kmac_mode_cshake_t
mode,
const
dif_kmac_function_name_t
*n,
586
const
dif_kmac_customization_string_t
*s);
587
588
/**
589
* Start a KMAC operation.
590
*
591
* To use KMAC in eXtendable-Output Function (XOF) mode set the output length
592
* (`l`) to 0. The output length must not be greater than
593
* `kDifKmacMaxOutputLenWords`.
594
*
595
* The key provided must have at least as many bits as the security strength
596
* of the `mode`.
597
*
598
* See NIST Special Publication 800-185 [2] for more information about KMAC.
599
*
600
* @param kmac A KMAC handle.
601
* @param operation_state A KMAC operation state context.
602
* @param mode The mode of operation.
603
* @param l Output length (number of 32-bit words that will be 'squeezed').
604
* @param k Pointer to secret key.
605
* @param s Customization string (optional).
606
* @return The result of the operation.
607
*/
608
OT_WARN_UNUSED_RESULT
609
dif_result_t
dif_kmac_mode_kmac_start
(
610
const
dif_kmac_t
*kmac,
dif_kmac_operation_state_t
*operation_state,
611
dif_kmac_mode_kmac_t
mode,
size_t
l,
const
dif_kmac_key_t
*k,
612
const
dif_kmac_customization_string_t
*s);
613
614
/**
615
* Absorb bytes from the message provided.
616
*
617
* If `processed` is non-NULL, then this function will write the remaining
618
* space in the FIFO and update `processed` with the number of bytes written.
619
* The caller should adjust the `msg` pointer and `len` parameters and call
620
* again as needed until all input has been written.
621
*
622
* If `processed` is NULL, then this function will block until the entire
623
* message has been processed or an error occurs.
624
*
625
* If big-endian mode is enabled for messages (`message_big_endian`) only the
626
* part of the message aligned to 32-bit word boundaries will be byte swapped.
627
* Unaligned leading and trailing bytes will be written into the message as-is.
628
*
629
* @param kmac A KMAC handle.
630
* @param operation_state A KMAC operation state context.
631
* @param msg Pointer to data to absorb.
632
* @param len Number of bytes of data to absorb.
633
* @param[out] processed Number of bytes processed (optional).
634
* @preturn The result of the operation.
635
*/
636
OT_WARN_UNUSED_RESULT
637
dif_result_t
dif_kmac_absorb
(
const
dif_kmac_t
*kmac,
638
dif_kmac_operation_state_t
*operation_state,
639
const
void
*msg,
size_t
len,
size_t
*processed);
640
641
/**
642
* Squeeze bytes into the output buffer provided.
643
*
644
* Requesting a squeeze operation will prevent any further absorption operations
645
* from taking place.
646
*
647
* If `kDifKmacIncomplete` is returned then the hardware is currently
648
* recomputing the state and the output was only partially written. The output
649
* pointer and length should be updated according to the number of bytes
650
* processed and the squeeze operation continued at a later time.
651
*
652
* If `processed` is not provided then this function will block until `len`
653
* bytes have been written to `out` or an error occurs.
654
*
655
* @param kmac A KMAC handle.
656
* @param operation_state A KMAC operation state context.
657
* @param[out] out Pointer to output buffer.
658
* @param[out] len Number of 32-bit words to write to output buffer.
659
* @param[out] processed Number of 32-bit words written to output buffer
660
* (optional).
661
* @preturn The result of the operation.
662
*/
663
OT_WARN_UNUSED_RESULT
664
dif_result_t
dif_kmac_squeeze
(
const
dif_kmac_t
*kmac,
665
dif_kmac_operation_state_t
*operation_state,
666
uint32_t *out,
size_t
len,
size_t
*processed);
667
668
/**
669
* Ends a squeeze operation and resets the hardware so it is ready for a new
670
* operation.
671
*
672
* @param kmac A KMAC handle.
673
* @param operation_state A KMAC operation state context.
674
* @return The result of the operation.
675
*/
676
OT_WARN_UNUSED_RESULT
677
dif_result_t
dif_kmac_end
(
const
dif_kmac_t
*kmac,
678
dif_kmac_operation_state_t
*operation_state);
679
680
/**
681
* Read the kmac error register to get the error code indicated the interrupt
682
* state.
683
*
684
* This function should be called in case of any of the `start` functions
685
* returns `kDifError`.
686
*
687
* @param kmac A KMAC handle.
688
* @param[out] error The current error code.
689
* @return The result of the operation.
690
*/
691
OT_WARN_UNUSED_RESULT
692
dif_result_t
dif_kmac_get_error
(
const
dif_kmac_t
*kmac,
693
dif_kmac_error_t
*error);
694
695
/**
696
* Clear the current error code and reset the state machine to the idle state
697
* ready to accept new operations.
698
*
699
* The state of any in-progress operation will be lost and the operation will
700
* need to be restarted.
701
*
702
* @param kmac A KMAC handle.
703
* @param operation_state A KMAC operation state context.
704
* @return The result of the operation.
705
*/
706
OT_WARN_UNUSED_RESULT
707
dif_result_t
dif_kmac_reset
(
const
dif_kmac_t
*kmac,
708
dif_kmac_operation_state_t
*operation_state);
709
710
/**
711
* Fetch the current status of the message FIFO used to buffer absorbed data.
712
*
713
* @param kmac A KMAC handle.
714
* @param[out] kmac_status The kmac status struct.
715
* @return The result of the operation.
716
*/
717
OT_WARN_UNUSED_RESULT
718
dif_result_t
dif_kmac_get_status
(
const
dif_kmac_t
*kmac,
719
dif_kmac_status_t
*kmac_status);
720
721
/**
722
* Returns the current value of the refresh hash counter.
723
*
724
* @param kmac A KMAC handle.
725
* @param hash_ctr The hash counter value that is returned.
726
* @return The result of the operation.
727
*/
728
OT_WARN_UNUSED_RESULT
729
dif_result_t
dif_kmac_get_hash_counter
(
const
dif_kmac_t
*kmac,
730
uint32_t *hash_ctr);
731
732
/**
733
* Reports whether or not the KMAC configuration register is locked.
734
*
735
* If writes to the KMAC configuration register are disabled (locked) then it is
736
* not possible to change any configuration parameters or start a new operation.
737
* The configuration register is locked when an operation has been started and
738
* is unlocked again when it completes.
739
*
740
* @param kmac A KMAC handle.
741
* @param[out] is_locked Out-param reporting the lock state.
742
* @return The result of the operation.
743
*/
744
OT_WARN_UNUSED_RESULT
745
dif_result_t
dif_kmac_config_is_locked
(
const
dif_kmac_t
*kmac,
bool
*is_locked);
746
747
/**
748
* Poll until a given flag in the status register is set.
749
*
750
* @param kmac A KMAC handle.
751
* @param flag the
752
* @return The result of the operation.
753
*/
754
OT_WARN_UNUSED_RESULT
755
dif_result_t
dif_kmac_poll_status
(
const
dif_kmac_t
*kmac, uint32_t flag);
756
757
#ifdef __cplusplus
758
}
// extern "C"
759
#endif // __cplusplus
760
761
#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_KMAC_H_
Return to
OpenTitan Documentation