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 AESCMACLPF3.h
34 *
35 * @brief AESCMAC (CMAC & CBC-MAC) 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 * The following limitations apply to the AESCCMLPF3 Driver for CC27xx device family only:
50 * - The CryptoKey input must have the correct encoding, @ref CryptoKey.h.
51 * - The application can only use one handle per driver.
52 * Concurrent dynamic instances will be supported in the future.
53 * - CCM driver only supports polling return behaviour.
54 * Blocking and callback return behaviours will be supported in the future.
55 *
56 * # Runtime Parameter Validation #
57 * The driver implementation does not perform runtime checks for most input parameters.
58 * Only values that are likely to have a stochastic element to them are checked (such
59 * as whether a driver is already open). Higher input parameter validation coverage is
60 * achieved by turning on assertions when compiling the driver.
61 */
62
63 #ifndef ti_drivers_aescmac_AESCMACLPF3__include
64 #define ti_drivers_aescmac_AESCMACLPF3__include
65
66 #include <stdbool.h>
67 #include <stdint.h>
68
69 #include <ti/drivers/AESCMAC.h>
70 #include <ti/drivers/cryptoutils/aes/AESCommonLPF3.h>
71 #include <ti/drivers/cryptoutils/sharedresources/CryptoResourceLPF3.h>
72
73 #include <ti/devices/DeviceFamily.h>
74 #include DeviceFamily_constructPath(inc/hw_types.h)
75 #include DeviceFamily_constructPath(driverlib/aes.h)
76
77 #ifdef __cplusplus
78 extern "C" {
79 #endif
80
81 /*
82 * Default AES CMAC & CBC-MAC auto config:
83 * ECB SRC as TXTXBUF
84 * Trigger point for auto ECB as WRBUF3 (encryption starts by writing BUF3)
85 * BUSHALT enabled
86 */
87 #if DeviceFamily_PARENT == DeviceFamily_PARENT_CC23X0
88 #define AESCMACLPF3_DEFAULT_AUTOCFG \
89 ((uint32_t)AES_AUTOCFG_AESSRC_TXTXBUF | (uint32_t)AES_AUTOCFG_TRGAES_WRBUF3 | (uint32_t)AES_AUTOCFG_BUSHALT_EN)
90 #elif DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX
91 #define AESCMACLPF3_DEFAULT_AUTOCFG \
92 ((uint32_t)AES_AUTOCFG_ECBSRC_TXTXBUF | (uint32_t)AES_AUTOCFG_TRGECB_WRBUF3 | (uint32_t)AES_AUTOCFG_BUSHALT_EN)
93 #else
94 #error "Unsupported DeviceFamily_Parent for AESCMACLPF3!"
95 #endif
96
97 /*
98 * AES CMAC DMA config:
99 * - ADRCHA = BUF0
100 * - TRGCHA = ECBSTART
101 */
102 #if DeviceFamily_PARENT == DeviceFamily_PARENT_CC23X0
103 #define AESCMACLPF3_DMA_CONFIG ((uint32_t)AES_DMA_ADRCHA_BUF0 | (uint32_t)AES_DMA_TRGCHA_AESSTART)
104 #elif DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX
105 #define AESCMACLPF3_DMA_CONFIG ((uint32_t)AES_DMA_ADRCHA_BUF0 | (uint32_t)AES_DMA_TRGCHA_ECBSTART)
106 #else
107 #error "Unsupported DeviceFamily_Parent for AESCMACLPF3!"
108 #endif
109
110 #define AESCBCMACLPF3_DMA_CONFIG AESCMACLPF3_DMA_CONFIG
111
112 /*!
113 * @brief AESCMACLPF3 Hardware Attributes
114 *
115 * AESCMACLPF3 hardware attributes should be included in the board file
116 * and pointed to by the AESCMAC_config struct.
117 */
118 typedef AESCommonLPF3_HWAttrs AESCMACLPF3_HWAttrs;
119
120 /*!
121 * @brief AESCMACLPF3 Object
122 *
123 * The application must not access any member variables of this structure!
124 */
125 typedef struct
126 {
127 /* Common member first to allow struct to be cast to the common type */
128 AESCommonLPF3_Object common;
129 volatile uint32_t intermediateTag[AES_TAG_LENGTH_BYTES / 4U];
130 uint32_t finalInputBlock[AES_BLOCK_SIZE_WORDS];
131 AESCMAC_CallbackFxn callbackFxn;
132 AESCMAC_Operation *operation;
133 AESCMAC_OperationType operationType;
134 AESCMAC_OperationalMode operationalMode;
135 bool threadSafe;
136 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)
137 size_t inputLength;
138 /*!
139 * @brief The staus of the HSM Boot up process
140 * if HSMLPF3_STATUS_SUCCESS, the HSM booted properly.
141 * if HSMLPF3_STATUS_ERROR, the HSM did not boot properly.
142 */
143 int_fast16_t hsmStatus;
144 uint32_t tempAssetID;
145 uint32_t keyAssetID;
146 /* To indicate whether a segmented operation is in progress
147 */
148 bool segmentedOperationInProgress;
149 #endif
150 } AESCMACLPF3_Object;
151
152 /*! @cond NODOC */
153
154 /*!
155 * @brief Processes the input blocks to generate the tag
156 *
157 * @param [in] input Pointer to the input data
158 * @param [in] transactionLength Length of the input to process. Should be a block-size multiple.
159 *
160 * @return none
161 */
162 void AESCMACLPF3_processBlocks(const uint8_t *input, size_t transactionLength);
163
164 /*!
165 * @brief Waits for the AES HW computation to complete and reads the tag output
166 *
167 * @param [out] tagOut Pointer to a block-sized array where the output tag should be stored.
168 *
169 * @return none
170 */
171 void AESCMACLPF3_readTag(uint32_t tagOut[AES_TAG_LENGTH_BYTES / 4U]);
172
173 /*! @endcond */
174
175 /*!
176 * @cond NODOC
177 *
178 * @brief Acquire Lock on Crypto Resource. This is an internal function that
179 * that may be called by other drivers to handle thread safety directly.
180 *
181 * @param [in] handle AESCMAC handle
182 * @param [in] timeout Timeout (in ClockP ticks) to wait for the semaphore.
183 * - @ref SemaphoreP_WAIT_FOREVER
184 * - @ref SemaphoreP_NO_WAIT
185 *
186 * @return true - Succeeded acquiring the lock on crypto resource
187 * false - Failed to acquire the lock on crypto resource
188 */
AESCMAC_acquireLock(AESCMAC_Handle handle,uint32_t timeout)189 __STATIC_INLINE bool AESCMAC_acquireLock(AESCMAC_Handle handle, uint32_t timeout)
190 {
191 return CryptoResourceLPF3_acquireLock(timeout);
192 }
193 /*! @endcond */
194
195 /*!
196 * @cond NODOC
197 *
198 * @brief Release Lock on Crypto Resource. This is an internal function that
199 * that may be called by other drivers to handle thread safety directly.
200 *
201 * @param [in] handle AESCMAC handle
202 */
AESCMAC_releaseLock(AESCMAC_Handle handle)203 __STATIC_INLINE void AESCMAC_releaseLock(AESCMAC_Handle handle)
204 {
205 CryptoResourceLPF3_releaseLock();
206 }
207 /*! @endcond */
208
209 /*!
210 * @cond NODOC
211 *
212 * @brief Enable thread safety. This is an internal function that
213 * that may be called by other drivers to handle thread safety directly.
214 *
215 * @param [in] handle AESCMAC handle
216 */
AESCMAC_enableThreadSafety(AESCMAC_Handle handle)217 __STATIC_INLINE void AESCMAC_enableThreadSafety(AESCMAC_Handle handle)
218 {
219 AESCMACLPF3_Object *object = handle->object;
220 object->threadSafe = true;
221 }
222 /*! @endcond */
223
224 /*!
225 * @cond NODOC
226 *
227 * @brief Disable thread safety. This is an internal function that
228 * that may be called by other drivers to handle thread safety directly.
229 *
230 * @note The user is responsible for reenabling thread safety after being
231 * done with the need for this driver.
232 *
233 * @param [in] handle AESCMAC handle
234 */
AESCMAC_disableThreadSafety(AESCMAC_Handle handle)235 __STATIC_INLINE void AESCMAC_disableThreadSafety(AESCMAC_Handle handle)
236 {
237 AESCMACLPF3_Object *object = handle->object;
238 object->threadSafe = false;
239 }
240 /*! @endcond */
241
242 #ifdef __cplusplus
243 }
244 #endif
245
246 #endif /* ti_drivers_aescmac_AESCMACLPF3__include */
247
