1 // Copyright 2019-2020 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 
15 #pragma once
16 
17 #include "hal/sha_types.h"
18 
19 /** @brief Low-level support functions for the hardware SHA engine using DMA
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  * - The crypto DMA is shared between the SHA and AES engine, it is not
30  *   possible for them to run calcalutions in parallel.
31  *
32  */
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 
39 /** @brief Calculate SHA1 or SHA2 sum of some data, using hardware SHA engine
40  *
41  * @note For more versatile SHA calculations, where data doesn't need
42  * to be passed all at once, try the mbedTLS mbedtls/shaX.h APIs.
43  *
44  * @note It is not necessary to lock any SHA hardware before calling
45  * this function, thread safety is managed internally.
46  *
47  * @param sha_type SHA algorithm to use.
48  *
49  * @param input Input data buffer.
50  *
51  * @param ilen Length of input data in bytes.
52  *
53  * @param output Buffer for output SHA digest. Output is 20 bytes for
54  * sha_type SHA1, 32 bytes for sha_type SHA2_256, 48 bytes for
55  * sha_type SHA2_384, 64 bytes for sha_type SHA2_512.
56  */
57 void esp_sha(esp_sha_type sha_type, const unsigned char *input, size_t ilen, unsigned char *output);
58 
59 /** @brief Execute SHA block operation using DMA
60  *
61  * @note This is a piece of a SHA algorithm, rather than an entire SHA
62  * algorithm.
63  *
64  * @note Call esp_sha_aquire_hardware() before calling this
65  * function.
66  *
67  * @param sha_type SHA algorithm to use.
68  *
69  * @param input Pointer to the input data. Block size is
70  * determined by algorithm (SHA1/SHA2_256 = 64 bytes,
71  * SHA2_384/SHA2_512 = 128 bytes)
72  *
73  * @param ilen length of input data should be multiple of block length.
74  *
75  * @param buf Pointer to blocks of data that will be prepended
76  * to data_block before hashing. Useful when there is two sources of
77  * data that need to be efficiently calculated in a single SHA DMA
78  * operation.
79  *
80  * @param buf_len length of buf data should be multiple of block length.
81  * Should not be longer than the maximum amount of bytes in a single block
82  * (128 bytes)
83  *
84  * @param is_first_block If this parameter is true, the SHA state will
85  * be initialised (with the initial state of the given SHA algorithm)
86  * before the block is calculated. If false, the existing state of the
87  * SHA engine will be used.
88  *
89  * @param t The number of bits for the SHA512/t hash function, with
90  * output truncated to t bits. Used for calculating the inital hash.
91  * t is any positive integer between 1 and 512, except 384.
92  *
93  * @return 0 if successful
94  */
95 int esp_sha_dma(esp_sha_type sha_type, const void *input, uint32_t ilen,
96                 const void *buf, uint32_t buf_len, bool is_first_block);
97 
98 /**
99  * @brief Read out the current state of the SHA digest
100  *
101  * @note This is a piece of a SHA algorithm, rather than an entire SHA algorithm.
102  *
103  * @note Call esp_sha_aquire_hardware() before calling this
104  * function.
105  *
106  * If the SHA suffix padding block has been executed already, the
107  * value that is read is the SHA digest.
108  * Otherwise, the value that is read is an interim SHA state.
109  *
110  * @param sha_type SHA algorithm in use.
111  * @param digest_state Pointer to a memory buffer to hold the SHA state. Size
112  * is 20 bytes (SHA1), 32 bytes (SHA2_256), or 64 bytes (SHA2_384, SHA2_512).
113  */
114 void esp_sha_read_digest_state(esp_sha_type sha_type, void *digest_state);
115 
116 /**
117  * @brief Set the current state of the SHA digest
118  *
119  * @note Call esp_sha_aquire_hardware() before calling this
120  * function.
121  *
122  * When resuming a
123  *
124  * @param sha_type SHA algorithm in use.
125  * @param digest_state
126  */
127 void esp_sha_write_digest_state(esp_sha_type sha_type, void *digest_state);
128 
129 
130 /**
131  * @brief Enables the SHA and crypto DMA peripheral and takes the
132  * locks for both of them.
133  */
134 void esp_sha_acquire_hardware(void);
135 
136 /**
137  * @brief Disables the SHA and crypto DMA peripheral and releases the
138  * locks.
139  */
140 void esp_sha_release_hardware(void);
141 
142 /**
143  * @brief Sets the initial hash value for SHA512/t.
144  *
145  * @note Is generated according to the algorithm described in the TRM,
146  * chapter SHA-Accelerator
147  *
148  * @note The engine must be locked until the value is used for an operation
149  * or read out. Else you risk another operation overwriting it.
150  *
151  * @param t
152  *
153  * @return 0 if successful
154  */
155 int esp_sha_512_t_init_hash(uint16_t t);
156 
157 #ifdef __cplusplus
158 }
159 #endif
160