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
