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       AESCCMLPF3.h
34  *
35  *  @brief      AESCCM driver implementation for the Low Power F3 family
36  *
37  *  # CCM Specification
38  *  This implementation follows NIST 800-38c -
39  *  https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38c.pdf
40  *  All symbols used in the implementation for identifiers and in the comments including
41  *  but not limited to B0, B1 and S0 are all adopted from this NIST 800-38c.
42  *
43  * # Hardware Accelerator #
44  * The Low Power F3 family of devices has dedicated hardware accelerators.
45  * CC23XX devices have one dedicated accelerator whereas CC27XX devices have two
46  * (Primary and Secondary). Combined they can perform AES encryption operations with
47  * 128-bit, 192-bit and 256-bit keys. Only one operation can be carried out on the
48  * accelerator at a time. Mutual exclusion is implemented at the driver level and
49  * coordinated between all drivers relying on the accelerator. It is transparent to
50  * the application and only noted to ensure sensible access timeouts are set.
51  *
52  *  # Implementation Limitations
53  *  - Only plaintext CryptoKeys are supported by this implementation.
54  *  - Maximum AAD length is limited to 65279-bytes.
55  *
56  *  The following limitations apply to the AESCCMLPF3 Driver for CC27xx device family only:
57  *  - The CryptoKey input must have the correct encoding, @ref CryptoKey.h.
58  *  - The application can only use one handle per driver.
59  *    Concurrent dynamic instances will be supported in the future.
60  *  - CCM driver only supports polling return behaviour.
61  *    Blocking and callback return behaviours will be supported in the future.
62  *
63  *  # Runtime Parameter Validation #
64  *  The driver implementation does not perform runtime checks for most input parameters.
65  *  Only values that are likely to have a stochastic element to them are checked (such
66  *  as whether a driver is already open). Higher input parameter validation coverage is
67  *  achieved by turning on assertions when compiling the driver.
68  */
69 
70 #ifndef ti_drivers_aesccm_AESCCMLPF3__include
71 #define ti_drivers_aesccm_AESCCMLPF3__include
72 
73 #include <stdbool.h>
74 #include <stdint.h>
75 
76 #include <ti/drivers/AESCCM.h>
77 #include <ti/drivers/cryptoutils/aes/AESCommonLPF3.h>
78 
79 #include <ti/devices/DeviceFamily.h>
80 #include DeviceFamily_constructPath(driverlib/aes.h)
81 
82 #ifdef __cplusplus
83 extern "C" {
84 #endif
85 
86 #define AESCCMLPF3_AAD_BUFFER_SIZE 2U
87 
88 /*!
89  *  @brief      AESCCMLPF3 Hardware Attributes
90  *
91  *  AESCCMLPF3 hardware attributes should be included in the board file
92  *  and pointed to by the AESCCM_config struct.
93  */
94 typedef AESCommonLPF3_HWAttrs AESCCMLPF3_HWAttrs;
95 
96 /*!
97  *  @brief      AESCCMLPF3 Object
98  *
99  *  The application must not access any member variables of this structure!
100  */
101 typedef struct
102 {
103     /* Common member first to allow struct to be cast to the common type */
104     AESCommonLPF3_Object common;
105     const uint8_t *aad;
106     const uint8_t *input;
107     uint8_t *output;
108     const uint8_t *nonce;
109     uint8_t *mac;
110     volatile uint32_t intermediateCounter[AES_IV_LENGTH_BYTES / 4];
111     volatile uint32_t intermediateTag[AES_TAG_LENGTH_BYTES / 4];
112     AESCCM_CallbackFxn callbackFxn;
113     AESCCM_OperationUnion *operation;
114     size_t inputLength;
115     volatile size_t inputCBCMACLengthRemaining;
116     volatile size_t inputCTRLengthRemaining;
117     size_t totalAADLength;
118     size_t totalDataLength;
119     size_t aadBytesProcessed;
120     volatile size_t totalCBCMACLengthRemaining;
121     volatile size_t totalCTRLengthRemaining;
122     AESCCM_OperationType operationType;
123     uint8_t bufferedAAD[AESCCMLPF3_AAD_BUFFER_SIZE];
124     uint8_t bufferedAADLength;
125     uint8_t macLength;
126     uint8_t nonceLength;
127 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)
128     size_t aadLength;
129     volatile size_t totalDataLengthRemaining;
130     volatile size_t totalAADLengthRemaining;
131     /*!
132      * @brief The staus of the HSM Boot up process
133      * if HSMLPF3_STATUS_SUCCESS, the HSM booted properly.
134      * if HSMLPF3_STATUS_ERROR, the HSM did not boot properly.
135      */
136     int_fast16_t hsmStatus;
137     uint32_t tempAssetID;
138     /* To indicate whether a segmented operation is in progress
139      */
140     bool segmentedOperationInProgress;
141 #endif
142 } AESCCMLPF3_Object;
143 
144 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)
145 /*!
146  *  @brief  Function to set the mac for an AES CCM segmented operation.
147  *          This API needs to be called only when the subsequent #AESCCM_addData() operation is processing all of the
148  * remaining data in a single call.
149  *
150  *  @note   This API is only concerned with segmented decryption operations.
151  *
152  *  @pre    #AESCCM_setupDecrypt(), #AESCCM_setLengths(), or #AESCCM_addAAD()
153  *
154  *  @param  [in] handle           A CCM handle returned from #AESCCM_open()
155  *                                or #AESCCM_construct()
156  *
157  *  @param  [in] mac            Pointer to the buffer containing the mac
158  *
159  *  @param  [in] macLength      The length of the mac in bytes
160  *
161  *  @retval #AESCCM_STATUS_SUCCESS                  The operation succeeded.
162  *  @retval #AESCCM_STATUS_ERROR                    The operation failed.
163  *  @retval #AESCCM_STATUS_FEATURE_NOT_SUPPORTED    The operation is not
164  *                                                  supported in this device.
165  *
166  *  @post   #AESCCM_addData()
167  */
168 int_fast16_t AESCCMLPF3HSM_setMac(AESCCM_Handle handle, const uint8_t *mac, size_t macLength);
169 #endif
170 
171 #ifdef __cplusplus
172 }
173 #endif
174 
175 #endif /* ti_drivers_aesccm_AESCCMLPF3__include */
176