1 // Copyright 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 /*******************************************************************************
16  * NOTICE
17  * The hal is not public api, don't use in application code.
18  * See readme.md in soc/include/hal/readme.md
19  ******************************************************************************/
20 
21 #pragma once
22 
23 #include <stddef.h>
24 #include <stdbool.h>
25 #include "soc/soc_caps.h"
26 #include "hal/aes_types.h"
27 #include "hal/aes_ll.h"
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 
34 /**
35  * @brief Sets the key used for AES encryption/decryption
36  *
37  * @param key pointer to the key
38  * @param key_bytes number of bytes in key
39  * @param mode key mode, 0 : decrypt, 1: encrypt
40  *
41  * @return uint8_t number of key bytes written to hardware, used for fault injection check
42  */
43 uint8_t aes_hal_setkey(const uint8_t *key, size_t key_bytes, int mode);
44 
45 /**
46  * @brief encrypts/decrypts a single block
47  *
48  * @param input_block input block, size of AES_BLOCK_BYTES
49  * @param output_block output block, size of AES_BLOCK_BYTES
50  */
51 void aes_hal_transform_block(const void *input_block, void *output_block);
52 
53 #if SOC_AES_SUPPORT_DMA
54 /**
55  * @brief Inits the AES mode of operation
56  *
57  * @param mode mode of operation, e.g. CTR or CBC
58  */
59 void aes_hal_mode_init(esp_aes_mode_t mode);
60 
61 /**
62  * @brief Sets the initialization vector for the transform
63  *
64  * @note The same IV must never be reused with the same key
65  *
66  * @param iv the initialization vector, length = IV_BYTES (16 bytes)
67  */
68 void aes_hal_set_iv(const uint8_t *iv);
69 
70 /**
71  * @brief Reads the initialization vector
72  *
73  * @param iv initialization vector read from HW, length = IV_BYTES (16 bytes)
74  */
75 void aes_hal_read_iv(uint8_t *iv);
76 
77 /**
78  * @brief Busy waits until the AES operation is done
79  *
80  * @param output pointer to inlink descriptor
81  */
82 void aes_hal_wait_done(void);
83 
84 /**
85  * @brief Starts an already configured AES DMA transform
86  *
87  * @param num_blocks Number of blocks to transform
88  */
89 void aes_hal_transform_dma_start(size_t num_blocks);
90 
91 /**
92  * @brief Finish up a AES DMA conversion, release DMA
93  *
94  */
95 void aes_hal_transform_dma_finish(void);
96 
97 /**
98  * @brief Enable or disable transform completed interrupt
99  *
100  * @param enable true to enable, false to disable.
101  */
102 #define aes_hal_interrupt_enable(enable) aes_ll_interrupt_enable(enable)
103 
104 /**
105  * @brief Clears the interrupt
106  *
107  */
108 #define aes_hal_interrupt_clear() aes_ll_interrupt_clear()
109 
110 #if SOC_AES_SUPPORT_GCM
111 /**
112  * @brief Calculates the Hash sub-key H0 needed to start AES-GCM
113  *
114  * @param gcm_hash the Hash sub-key H0 output
115  */
116 void aes_hal_gcm_calc_hash(uint8_t *gcm_hash);
117 
118 /**
119  * @brief Initializes the AES hardware for AES-GCM
120  *
121  * @param aad_num_blocks the number of Additional Authenticated Data (AAD) blocks
122  * @param num_valid_bit the number of effective bits of incomplete blocks in plaintext/cipertext
123  */
124 void aes_hal_gcm_init(size_t aad_num_blocks, size_t num_valid_bit);
125 
126 /**
127  * @brief Starts a AES-GCM transform
128  *
129  * @param num_blocks Number of blocks to transform
130  */
131 void aes_hal_transform_dma_gcm_start(size_t num_blocks);
132 
133 /**
134  * @brief Sets the J0 value, for more information see the GCM subchapter in the TRM
135  *
136  * @note Only affects AES-GCM
137  *
138  * @param j0 J0 value
139  */
140 #define aes_hal_gcm_set_j0(j0)  aes_ll_gcm_set_j0(j0)
141 
142 /**
143  * @brief Read the tag after a AES-GCM transform
144  *
145  * @param tag Pointer to where to store the result
146  * @param tag_length number of bytes to read into tag
147  */
148 void aes_hal_gcm_read_tag(uint8_t *tag, size_t tag_len);
149 
150 #endif //SOC_AES_SUPPORT_GCM
151 
152 #endif //SOC_AES_SUPPORT_DMA
153 
154 
155 #ifdef __cplusplus
156 }
157 #endif
158