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