1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 
7 //     http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 #pragma once
15 
16 #include "hal/sha_types.h"
17 #include "esp_types.h"
18 
19 /** @brief Low-level support functions for the hardware SHA engine
20  *
21  * @note If you're looking for a SHA API to use, try mbedtls component
22  * mbedtls/shaXX.h. That API supports hardware acceleration.
23  *
24  * The API in this header provides some building blocks for implementing a
25  * full SHA API such as the one in mbedtls, and also a basic SHA function esp_sha().
26  *
27  * Some technical details about the hardware SHA engine:
28  *
29  * - SHA accelerator engine calculates one digest at a time, per SHA
30  *   algorithm type. It initialises and maintains the digest state
31  *   internally. It is possible to read out an in-progress SHA digest
32  *   state, but it is not possible to restore a SHA digest state
33  *   into the engine.
34  *
35  * - The memory block SHA_TEXT_BASE is shared between all SHA digest
36  *   engines, so all engines must be idle before this memory block is
37  *   modified.
38  *
39  */
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 
46 /** @brief Calculate SHA1 or SHA2 sum of some data, using hardware SHA engine
47  *
48  * @note For more versatile SHA calculations, where data doesn't need
49  * to be passed all at once, try the mbedTLS mbedtls/shaX.h APIs. The
50  * hardware-accelerated mbedTLS implementation is also faster when
51  * hashing large amounts of data.
52  *
53  * @note It is not necessary to lock any SHA hardware before calling
54  * this function, thread safety is managed internally.
55  *
56  * @note If a TLS connection is open then this function may block
57  * indefinitely waiting for a SHA engine to become available. Use the
58  * mbedTLS SHA API to avoid this problem.
59  *
60  * @param sha_type SHA algorithm to use.
61  *
62  * @param input Input data buffer.
63  *
64  * @param ilen Length of input data in bytes.
65  *
66  * @param output Buffer for output SHA digest. Output is 20 bytes for
67  * sha_type SHA1, 32 bytes for sha_type SHA2_256, 48 bytes for
68  * sha_type SHA2_384, 64 bytes for sha_type SHA2_512.
69  */
70 void esp_sha(esp_sha_type sha_type, const unsigned char *input, size_t ilen, unsigned char *output);
71 
72 /* @brief Begin to execute a single SHA block operation
73  *
74  * @note This is a piece of a SHA algorithm, rather than an entire SHA
75  * algorithm.
76  *
77  * @note Call esp_sha_try_lock_engine() before calling this
78  * function. Do not call esp_sha_lock_memory_block() beforehand, this
79  * is done inside the function.
80  *
81  * @param sha_type SHA algorithm to use.
82  *
83  * @param data_block Pointer to block of data. Block size is
84  * determined by algorithm (SHA1/SHA2_256 = 64 bytes,
85  * SHA2_384/SHA2_512 = 128 bytes)
86  *
87  * @param is_first_block If this parameter is true, the SHA state will
88  * be initialised (with the initial state of the given SHA algorithm)
89  * before the block is calculated. If false, the existing state of the
90  * SHA engine will be used.
91  *
92  * @return As a performance optimisation, this function returns before
93  * the SHA block operation is complete. Both this function and
94  * esp_sha_read_state() will automatically wait for any previous
95  * operation to complete before they begin. If using the SHA registers
96  * directly in another way, call esp_sha_wait_idle() after calling this
97  * function but before accessing the SHA registers.
98  */
99 void esp_sha_block(esp_sha_type sha_type, const void *data_block, bool is_first_block);
100 
101 /** @brief Read out the current state of the SHA digest loaded in the engine.
102  *
103  * @note This is a piece of a SHA algorithm, rather than an entire SHA algorithm.
104  *
105  * @note Call esp_sha_try_lock_engine() before calling this
106  * function. Do not call esp_sha_lock_memory_block() beforehand, this
107  * is done inside the function.
108  *
109  * If the SHA suffix padding block has been executed already, the
110  * value that is read is the SHA digest (in big endian
111  * format). Otherwise, the value that is read is an interim SHA state.
112  *
113  * @note If sha_type is SHA2_384, only 48 bytes of state will be read.
114  * This is enough for the final SHA2_384 digest, but if you want the
115  * interim SHA-384 state (to continue digesting) then pass SHA2_512 instead.
116  *
117  * @param sha_type SHA algorithm in use.
118  *
119  * @param state Pointer to a memory buffer to hold the SHA state. Size
120  * is 20 bytes (SHA1), 32 bytes (SHA2_256), 48 bytes (SHA2_384) or 64 bytes (SHA2_512).
121  *
122  */
123 void esp_sha_read_digest_state(esp_sha_type sha_type, void *digest_state);
124 
125 /**
126  * @brief Obtain exclusive access to a particular SHA engine
127  *
128  * @param sha_type Type of SHA engine to use.
129  *
130  * Blocks until engine is available. Note: Can block indefinitely
131  * while a TLS connection is open, suggest using
132  * esp_sha_try_lock_engine() and failing over to software SHA.
133  */
134 void esp_sha_lock_engine(esp_sha_type sha_type);
135 
136 /**
137  * @brief Try and obtain exclusive access to a particular SHA engine
138  *
139  * @param sha_type Type of SHA engine to use.
140  *
141  * @return Returns true if the SHA engine is locked for exclusive
142  * use. Call esp_sha_unlock_sha_engine() when done.  Returns false if
143  * the SHA engine is already in use, caller should use software SHA
144  * algorithm for this digest.
145  */
146 bool esp_sha_try_lock_engine(esp_sha_type sha_type);
147 
148 /**
149  * @brief Unlock an engine previously locked with esp_sha_lock_engine() or esp_sha_try_lock_engine()
150  *
151  * @param sha_type Type of engine to release.
152  */
153 void esp_sha_unlock_engine(esp_sha_type sha_type);
154 
155 /**
156  * @brief Acquire exclusive access to the SHA shared memory block at SHA_TEXT_BASE
157  *
158  * This memory block is shared across all the SHA algorithm types.
159  *
160  * Caller should have already locked a SHA engine before calling this function.
161  *
162  * Note that it is possible to obtain exclusive access to the memory block even
163  * while it is in use by the SHA engine. Caller should use esp_sha_wait_idle()
164  * to ensure the SHA engine is not reading from the memory block in hardware.
165  *
166  * @note This function enters a critical section. Do not block while holding this lock.
167  *
168  * @note You do not need to lock the memory block before calling esp_sha_block() or esp_sha_read_digest_state(), these functions handle memory block locking internally.
169  *
170  * Call esp_sha_unlock_memory_block() when done.
171  */
172 void esp_sha_lock_memory_block(void);
173 
174 /**
175  * @brief Release exclusive access to the SHA register memory block at SHA_TEXT_BASE
176  *
177  * Caller should have already locked a SHA engine before calling this function.
178  *
179  * This function releases the critical section entered by esp_sha_lock_memory_block().
180  *
181  * Call following esp_sha_lock_memory_block().
182  */
183 void esp_sha_unlock_memory_block(void);
184 
185 /** @brief Wait for the SHA engine to finish any current operation
186  *
187  * @note This function does not ensure exclusive access to any SHA
188  * engine. Caller should use esp_sha_try_lock_engine() and
189  * esp_sha_lock_memory_block() as required.
190  *
191  * @note Functions declared in this header file wait for SHA engine
192  * completion automatically, so you don't need to use this API for
193  * these. However if accessing SHA registers directly, you will need
194  * to call this before accessing SHA registers if using the
195  * esp_sha_block() function.
196  *
197  * @note This function busy-waits, so wastes CPU resources.
198  * Best to delay calling until you are about to need it.
199  *
200  */
201 void esp_sha_wait_idle(void);
202 
203 #ifdef __cplusplus
204 }
205 #endif
206