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 AESECBLPF3.h
34 *
35 * @brief AESECB 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 * - Decryption is not supported since the AES HW only supports encryption.
48 * - Only plaintext CryptoKeys are supported by this implementation.
49 *
50 * # Runtime Parameter Validation #
51 * The driver implementation does not perform runtime checks for most input
52 * parameters. Only values that are likely to have a stochastic element to
53 * them are checked (such as whether a driver is already open). Higher input
54 * parameter validation coverage is achieved by turning on assertions when
55 * compiling the driver.
56 */
57
58 #ifndef ti_drivers_aesecb_AESECBLPF3__include
59 #define ti_drivers_aesecb_AESECBLPF3__include
60
61 #include <stdbool.h>
62 #include <stdint.h>
63
64 #include <ti/drivers/AESECB.h>
65 #include <ti/drivers/cryptoutils/aes/AESCommonLPF3.h>
66 #include <ti/drivers/cryptoutils/sharedresources/CryptoResourceLPF3.h>
67
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
71
72 /**
73 * The threshold at which blocking and callback mode transfers will utilize DMA.
74 * For data lengths below this threshold, polling CPU R/W will be used instead
75 * of DMA. With task switching and interrupt overhead, it is inefficient to
76 * utilize DMA for shorter length operations.
77 * The threshold value must be a multiple of AES_BLOCK_SIZE.
78 */
79 #define AESECBLPF3_DMA_SIZE_THRESHOLD (1U * AES_BLOCK_SIZE)
80
81 /*
82 * AES ECB auto config for a single block encryption:
83 * ECB SRC as BUF
84 * Trigger points for auto ECB as WRBUF3S (encryption starts by writing BUF3)
85 * BUSHALT enabled
86 */
87 #if DeviceFamily_PARENT == DeviceFamily_PARENT_CC23X0
88 #define AESEBCLPF3_SINGLE_BLOCK_AUTOCFG \
89 ((uint32_t)AES_AUTOCFG_AESSRC_BUF | (uint32_t)AES_AUTOCFG_TRGAES_WRBUF3S | (uint32_t)AES_AUTOCFG_BUSHALT_EN)
90 #elif DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX
91 #define AESEBCLPF3_SINGLE_BLOCK_AUTOCFG \
92 ((uint32_t)AES_AUTOCFG_ECBSRC_BUF | (uint32_t)AES_AUTOCFG_TRGECB_WRBUF3S | (uint32_t)AES_AUTOCFG_BUSHALT_EN)
93 #else
94 #error "Unsupported DeviceFamily_Parent for AESECBLPF3!"
95 #endif
96
97 /*!
98 * @brief AESECBLPF3 Hardware Attributes
99 *
100 * AESECBLPF3 hardware attributes should be included in the board file
101 * and pointed to by the AESECB_config struct.
102 */
103 typedef AESCommonLPF3_HWAttrs AESECBLPF3_HWAttrs;
104
105 /*!
106 * @brief AESECBLPF3 Object
107 *
108 * The application must not access any member variables of this structure!
109 */
110 typedef struct
111 {
112 /* Common member first to allow struct to be cast to the common type */
113 AESCommonLPF3_Object common;
114 AESECB_Operation *operation;
115 AESECB_CallbackFxn callbackFxn;
116 AESECB_OperationType operationType;
117 bool threadSafe;
118 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)
119 const uint8_t *input;
120 uint8_t *output;
121 size_t inputLength;
122 size_t totalDataLength;
123 volatile size_t totalDataLengthRemaining;
124 /*!
125 * @brief The staus of the HSM Boot up process
126 * if HSMLPF3_STATUS_SUCCESS, the HSM booted properly.
127 * if HSMLPF3_STATUS_ERROR, the HSM did not boot properly.
128 */
129 int_fast16_t hsmStatus;
130 /* To indicate whether a segmented operation is in progress
131 */
132 bool segmentedOperationInProgress;
133 #endif
134 } AESECBLPF3_Object;
135
136 /*!
137 * @cond NODOC
138 *
139 * @brief Helper function to encrypt plaintext input
140 *
141 * Writes the first block of data and calls #AESECBLPF3_processBlock()
142 *
143 * @note This will be reused for AES CBC mode which is why it's exposed here.
144 *
145 * @param [in] object Pointer to an #AESCommonLPF3_Object to track if
146 * a HW operation is in progress
147 * @param [in] input Plaintext input to be encrypted
148 * @param [out] output Buffer to store the decrypted ciphertext
149 * @param [in] inputLength Length of input to be encrypted
150 */
151 void AESECBLPF3_processData(AESCommonLPF3_Object *object, const uint8_t *input, uint8_t *output, size_t inputLength);
152 /*! @endcond */
153
154 /*!
155 * @cond NODOC
156 *
157 * @brief Acquire Lock on Crypto Resource. This is an internal function that
158 * that may be called by other drivers to handle thread safety directly.
159 *
160 * @param [in] handle AESECB handle
161 * @param [in] timeout Timeout (in ClockP ticks) to wait for the semaphore.
162 * - @ref SemaphoreP_WAIT_FOREVER
163 * - @ref SemaphoreP_NO_WAIT
164 *
165 * @return true - Succeeded acquiring the lock on crypto resource
166 * false - Failed to acquire the lock on crypto resource
167 */
AESECB_acquireLock(AESECB_Handle handle,uint32_t timeout)168 __STATIC_INLINE bool AESECB_acquireLock(AESECB_Handle handle, uint32_t timeout)
169 {
170 return CryptoResourceLPF3_acquireLock(timeout);
171 }
172 /*! @endcond */
173
174 /*!
175 * @cond NODOC
176 *
177 * @brief Release Lock on Crypto Resource. This is an internal function that
178 * that may be called by other drivers to handle thread safety directly.
179 *
180 * @param [in] handle AESECB handle
181 */
AESECB_releaseLock(AESECB_Handle handle)182 __STATIC_INLINE void AESECB_releaseLock(AESECB_Handle handle)
183 {
184 CryptoResourceLPF3_releaseLock();
185 }
186 /*! @endcond */
187
188 /*!
189 * @cond NODOC
190 *
191 * @brief Enable thread safety. This is an internal function that
192 * that may be called by other drivers to handle thread safety directly.
193 *
194 * @param [in] handle AESECB handle
195 */
AESECB_enableThreadSafety(AESECB_Handle handle)196 __STATIC_INLINE void AESECB_enableThreadSafety(AESECB_Handle handle)
197 {
198 AESECBLPF3_Object *object = handle->object;
199 object->threadSafe = true;
200 }
201 /*! @endcond */
202
203 /*!
204 * @cond NODOC
205 *
206 * @brief Disable thread safety. This is an internal function that
207 * that may be called by other drivers to handle thread safety directly.
208 *
209 * @note The user is responsible for reenabling thread safety after being
210 * done with the need for this driver.
211 *
212 * @param [in] handle AESECB handle
213 */
AESECB_disableThreadSafety(AESECB_Handle handle)214 __STATIC_INLINE void AESECB_disableThreadSafety(AESECB_Handle handle)
215 {
216 AESECBLPF3_Object *object = handle->object;
217 object->threadSafe = false;
218 }
219 /*! @endcond */
220
221 #ifdef __cplusplus
222 }
223 #endif
224
225 #endif /* ti_drivers_aesecb_AESECBLPF3__include */
226
