1 /*
2  * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #pragma once
8 
9 #include <stddef.h>
10 
11 #include "hal/sha_types.h"
12 
13 /** @brief Low-level support functions for the hardware SHA engine
14  *
15  * @note If you're looking for a SHA API to use, try mbedtls component
16  * mbedtls/shaXX.h. That API supports hardware acceleration.
17  *
18  * The API in this header provides some building blocks for implementing a
19  * full SHA API such as the one in mbedtls, and also a basic SHA function esp_sha().
20  *
21  */
22 
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26 
27 
28 /** @brief Calculate SHA1 or SHA2 sum of some data, using hardware SHA engine
29  *
30  * @note For more versatile SHA calculations, where data doesn't need
31  * to be passed all at once, try the mbedTLS mbedtls/shaX.h APIs.
32  *
33  * @note It is not necessary to lock any SHA hardware before calling
34  * this function, thread safety is managed internally.
35  *
36  * @param sha_type SHA algorithm to use.
37  *
38  * @param input Input data buffer.
39  *
40  * @param ilen Length of input data in bytes.
41  *
42  * @param output Buffer for output SHA digest. Output is 20 bytes for
43  * sha_type SHA1, 32 bytes for sha_type SHA2_256, 48 bytes for
44  * sha_type SHA2_384, 64 bytes for sha_type SHA2_512.
45  */
46 void esp_sha(esp_sha_type sha_type, const unsigned char *input, size_t ilen, unsigned char *output);
47 
48 /** @brief Execute SHA block operation
49  *
50  * @note This is a piece of a SHA algorithm, rather than an entire SHA
51  * algorithm.
52  *
53  * @note Call esp_sha_acquire_hardware() before calling this
54  * function.
55  *
56  * @param sha_type SHA algorithm to use.
57  *
58  * @param data_block Pointer to the input data. Block size is
59  * determined by algorithm (SHA1/SHA2_256 = 64 bytes,
60  * SHA2_384/SHA2_512 = 128 bytes)
61  *
62  * @param is_first_block If this parameter is true, the SHA state will
63  * be initialised (with the initial state of the given SHA algorithm)
64  * before the block is calculated. If false, the existing state of the
65  * SHA engine will be used.
66  *
67  */
68 void esp_sha_block(esp_sha_type sha_type, const void *data_block, bool is_first_block);
69 
70 /**
71  * @brief Read out the current state of the SHA digest
72  *
73  * @note This is a piece of a SHA algorithm, rather than an entire SHA algorithm.
74  *
75  * @note Call esp_sha_aquire_hardware() before calling this
76  * function.
77  *
78  * If the SHA suffix padding block has been executed already, the
79  * value that is read is the SHA digest.
80  * Otherwise, the value that is read is an interim SHA state.
81  *
82  * @param sha_type SHA algorithm in use.
83  * @param digest_state Pointer to a memory buffer to hold the SHA state. Size
84  * is 20 bytes (SHA1), 32 bytes (SHA2_256), or 64 bytes (SHA2_384, SHA2_512).
85  */
86 void esp_sha_read_digest_state(esp_sha_type sha_type, void *digest_state);
87 
88 /**
89  * @brief Set the current state of the SHA digest
90  *
91  * @note Call esp_sha_aquire_hardware() before calling this
92  * function.
93  *
94  * @param sha_type SHA algorithm in use.
95  * @param digest_state Digest state to write to hardware
96  */
97 void esp_sha_write_digest_state(esp_sha_type sha_type, void *digest_state);
98 
99 
100 /**
101  * @brief Enables the SHA peripheral and takes the lock.
102  */
103 void esp_sha_acquire_hardware(void);
104 
105 /**
106  * @brief Disables the SHA peripheral and releases the lock.
107  */
108 void esp_sha_release_hardware(void);
109 
110 
111 #ifdef __cplusplus
112 }
113 #endif
114