1 /*
2 * Copyright (c) 2021-2024, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32 /** ==========================================================================
33 * @file AESCTRLPF3.h
34 *
35 * @brief AESCTR driver implementation for the Low Power F3 family
36 *
37 * # Hardware Accelerator #
38 * The Low Power F3 family of devices has dedicated hardware accelerators.
39 * CC23XX devices have one dedicated accelerator whereas CC27XX devices have two
40 * (Primary and Secondary). Combined they can perform AES encryption operations with
41 * 128-bit, 192-bit and 256-bit keys. Only one operation can be carried out on the
42 * accelerator at a time. Mutual exclusion is implemented at the driver level and
43 * coordinated between all drivers relying on the accelerator. It is transparent to
44 * the application and only noted to ensure sensible access timeouts are set.
45 *
46 * # Implementation Limitations
47 * - Only plaintext CryptoKeys are supported by this implementation.
48 *
49 * # Runtime Parameter Validation #
50 * The driver implementation does not perform runtime checks for most input parameters.
51 * Only values that are likely to have a stochastic element to them are checked (such
52 * as whether a driver is already open). Higher input parameter validation coverage is
53 * achieved by turning on assertions when compiling the driver.
54 */
55
56 #ifndef ti_drivers_aesctr_AESCTRLPF3__include
57 #define ti_drivers_aesctr_AESCTRLPF3__include
58
59 #include <stdbool.h>
60 #include <stdint.h>
61
62 #include <ti/drivers/AESCTR.h>
63 #include <ti/drivers/cryptoutils/aes/AESCommonLPF3.h>
64 #include <ti/drivers/cryptoutils/sharedresources/CryptoResourceLPF3.h>
65
66 #include <ti/devices/DeviceFamily.h>
67 #include DeviceFamily_constructPath(driverlib/aes.h)
68
69 #ifdef __cplusplus
70 extern "C" {
71 #endif
72
73 /*
74 * Default AES CTR auto config:
75 * ECB SRC as BUF
76 * Trigger points for auto ECB as RDTX3 and WRBUF3S
77 * (the first encryption starts by writing BUF3, the successive ones by reading TXT3)
78 * Counter size as 128-bits
79 * Counter endianness as Big Endian
80 * BUSHALT enabled
81 */
82 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)
83 #define AES_AUTOCFG_CTRENDN_BIGENDIAN AES_AUTOCFG_CTRENDIAN_BIGENDIAN
84 #endif
85
86 #if DeviceFamily_PARENT == DeviceFamily_PARENT_CC23X0
87 #define AESCTRLPF3_DEFAULT_AUTOCFG \
88 ((uint32_t)AES_AUTOCFG_AESSRC_BUF | (uint32_t)AES_AUTOCFG_TRGAES_WRBUF3S | \
89 (uint32_t)AES_AUTOCFG_TRGAES_RDTXT3 | (uint32_t)AES_AUTOCFG_CTRSIZE_CTR128 | \
90 (uint32_t)AES_AUTOCFG_CTRENDN_BIGENDIAN | (uint32_t)AES_AUTOCFG_BUSHALT_EN)
91 #elif DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX
92 #define AESCTRLPF3_DEFAULT_AUTOCFG \
93 ((uint32_t)AES_AUTOCFG_ECBSRC_BUF | (uint32_t)AES_AUTOCFG_TRGECB_WRBUF3S | \
94 (uint32_t)AES_AUTOCFG_TRGECB_RDTXT3 | (uint32_t)AES_AUTOCFG_CTRSIZE_CTR128 | \
95 (uint32_t)AES_AUTOCFG_CTRENDN_BIGENDIAN | (uint32_t)AES_AUTOCFG_BUSHALT_EN)
96 #else
97 #error "Unsupported DeviceFamily_Parent for AESCTRLPF3!"
98 #endif
99
100 /*
101 * AES CTR auto config for handling processing of the last
102 * block of input to avoid starting encryption of the next counter block and
103 * incrementing the counter value when the output is read from TXT3.
104 *
105 * ECB SRC as BUF
106 * Trigger for auto ECB as WRBUF3S
107 * (the first encryption starts by writing BUF3)
108 * Counter size as 128-bits
109 * Counter endianness as Big Endian
110 */
111 #if DeviceFamily_PARENT == DeviceFamily_PARENT_CC23X0
112 #define AESCTRLPF3_LAST_BLOCK_AUTOCFG \
113 ((uint32_t)AES_AUTOCFG_AESSRC_BUF | (uint32_t)AES_AUTOCFG_TRGAES_WRBUF3S | \
114 (uint32_t)AES_AUTOCFG_CTRSIZE_CTR128 | (uint32_t)AES_AUTOCFG_CTRENDN_BIGENDIAN | \
115 (uint32_t)AES_AUTOCFG_BUSHALT_EN)
116 #elif DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX
117 #define AESCTRLPF3_LAST_BLOCK_AUTOCFG \
118 ((uint32_t)AES_AUTOCFG_ECBSRC_BUF | (uint32_t)AES_AUTOCFG_TRGECB_WRBUF3S | \
119 (uint32_t)AES_AUTOCFG_CTRSIZE_CTR128 | (uint32_t)AES_AUTOCFG_CTRENDN_BIGENDIAN | \
120 (uint32_t)AES_AUTOCFG_BUSHALT_EN)
121 #else
122 #error "Unsupported DeviceFamily_Parent for AESCTRLPF3!"
123 #endif
124
125 /*!
126 * @brief AESCTRLPF3 Hardware Attributes
127 *
128 * AESCTRLPF3 hardware attributes should be included in the board file
129 * and pointed to by the AESCTR_config struct.
130 */
131 typedef AESCommonLPF3_HWAttrs AESCTRLPF3_HWAttrs;
132
133 /*!
134 * @brief AESCTRLPF3 Object
135 *
136 * The application must not access any member variables of this structure!
137 */
138 typedef struct
139 {
140 /* Common member first to allow struct to be cast to the common type */
141 AESCommonLPF3_Object common;
142 volatile uint32_t counter[AES_BLOCK_SIZE_WORDS];
143 const uint8_t *input;
144 uint8_t *output;
145 size_t inputLength;
146 size_t inputLengthRemaining;
147 AESCTR_OperationUnion *operation;
148 AESCTR_CallbackFxn callbackFxn;
149 AESCTR_OperationType operationType;
150 bool threadSafe;
151 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)
152 /*!
153 * @brief The staus of the HSM Boot up process
154 * if HSMLPF3_STATUS_SUCCESS, the HSM booted properly.
155 * if HSMLPF3_STATUS_ERROR, the HSM did not boot properly.
156 */
157 int_fast16_t hsmStatus;
158 /* To indicate whether a segmented operation is in progress
159 */
160 bool segmentedOperationInProgress;
161 #endif
162 } AESCTRLPF3_Object;
163
164 /*! @cond NODOC */
165
166 /*!
167 * @brief Processes the given input data using CPU R/W.
168 *
169 * @param [in] input Pointer to the input data
170 * @param [out] output Pointer to the output data
171 * @param [in] inputLength Length of input data
172 * @param [in] isOneStepOrFinalOperation Set to True for one-step or finalization
173 * operation, False otherwise.
174 *
175 */
176 void AESCTRLPF3_processData(const uint8_t *input, uint8_t *output, size_t inputLength, bool isOneStepOrFinalOperation);
177
178 /*!
179 * @brief Configures the DMA to process the given input data.
180 * #AESCTRLPF3_writeCounter must be called to start the operation
181 *
182 * @param [in] object Pointer to an AESCommonLPF3_Object
183 * @param [in] input Pointer to the input data
184 * @param [out] output Pointer to the output data
185 * @param [in] inputLength Length of input data
186 *
187 * @return The number of bytes processed - a multiple of AES_BLOCK_SIZE.
188 */
189 size_t AESCTRLPF3_configDataDMA(AESCommonLPF3_Object *object,
190 const uint8_t *input,
191 uint8_t *output,
192 size_t inputLength);
193
194 /*!
195 * @brief Reads the latest counter value from the AES HW.
196 *
197 * @note AES HW must be idle (i.e. no active encryption) when reading the counter value.
198 *
199 * @param [out] counterOut Pointer to a block-sized array where the output counter should be stored.
200 */
AESCTRLPF3_readCounter(uint32_t counterOut[AES_BLOCK_SIZE_WORDS])201 __STATIC_INLINE void AESCTRLPF3_readCounter(uint32_t counterOut[AES_BLOCK_SIZE_WORDS])
202 {
203 /* Read the latest counter value from the AES engine */
204 AESReadBUF32(&counterOut[0]);
205 }
206
207 /*!
208 * @brief Writes the given counter into the AES HW
209 *
210 * @param [in] counterIn Pointer to a block-sized array of the input counter.
211 */
AESCTRLPF3_writeCounter(uint32_t counterIn[AES_BLOCK_SIZE_WORDS])212 __STATIC_INLINE void AESCTRLPF3_writeCounter(uint32_t counterIn[AES_BLOCK_SIZE_WORDS])
213 {
214 AESWriteBUF32(&counterIn[0]);
215 }
216
217 /*! @endcond */
218
219 /*!
220 * @cond NODOC
221 *
222 * @brief Acquire Lock on Crypto Resource. This is an internal function that
223 * that may be called by other drivers to handle thread safety directly.
224 *
225 * @param [in] handle An AESCTR handle
226 * @param [in] timeout Timeout (in ClockP ticks) to wait for the semaphore.
227 * - @ref SemaphoreP_WAIT_FOREVER
228 * - @ref SemaphoreP_NO_WAIT
229 *
230 * @return true - Succeeded acquiring the lock on crypto resource
231 * false - Failed to acquire the lock on crypto resource
232 */
AESCTR_acquireLock(AESCTR_Handle handle,uint32_t timeout)233 __STATIC_INLINE bool AESCTR_acquireLock(AESCTR_Handle handle, uint32_t timeout)
234 {
235 return CryptoResourceLPF3_acquireLock(timeout);
236 }
237 /*! @endcond */
238
239 /*!
240 * @cond NODOC
241 *
242 * @brief Release Lock on Crypto Resource. This is an internal function that
243 * that may be called by other drivers to handle thread safety directly.
244 *
245 * @param [in] handle An AESCTR handle
246 */
AESCTR_releaseLock(AESCTR_Handle handle)247 __STATIC_INLINE void AESCTR_releaseLock(AESCTR_Handle handle)
248 {
249 CryptoResourceLPF3_releaseLock();
250 }
251 /*! @endcond */
252
253 /*!
254 * @cond NODOC
255 *
256 * @brief Enable thread safety. This is an internal function that
257 * that may be called by other drivers to handle thread safety directly.
258 *
259 * @param [in] handle An AESCTR handle
260 */
AESCTR_enableThreadSafety(AESCTR_Handle handle)261 __STATIC_INLINE void AESCTR_enableThreadSafety(AESCTR_Handle handle)
262 {
263 AESCTRLPF3_Object *object = handle->object;
264 object->threadSafe = true;
265 }
266 /*! @endcond */
267
268 /*!
269 * @cond NODOC
270 *
271 * @brief Disable thread safety. This is an internal function that
272 * that may be called by other drivers to handle thread safety directly.
273 *
274 * @note The user is responsible for reenabling thread safety after being
275 * done with the need for this driver.
276 *
277 * @param [in] handle An AESCTR handle
278 */
AESCTR_disableThreadSafety(AESCTR_Handle handle)279 __STATIC_INLINE void AESCTR_disableThreadSafety(AESCTR_Handle handle)
280 {
281 AESCTRLPF3_Object *object = handle->object;
282 object->threadSafe = false;
283 }
284 /*! @endcond */
285
286 #ifdef __cplusplus
287 }
288 #endif
289
290 #endif /* ti_drivers_aesctr_AESCTRLPF3__include */
291
