1 /* 2 * Copyright (c) 2016, Freescale Semiconductor, Inc. 3 * Copyright 2016-2022 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 #ifndef FSL_SHA_H_ 9 #define FSL_SHA_H_ 10 11 #include "fsl_common.h" 12 /*! 13 * @addtogroup sha 14 * @{ 15 */ 16 17 /*! @file */ 18 19 /******************************************************************************* 20 * Definitions 21 *******************************************************************************/ 22 23 /*! @name Driver version */ 24 /*! @{ */ 25 /*! @brief Defines LPC SHA driver version 2.3.2. 26 * 27 * Current version: 2.3.2 28 * 29 * Change log: 30 * - Version 2.0.0 31 * - Initial version 32 * - Version 2.1.0 33 * - Updated "sha_ldm_stm_16_words" "sha_one_block" API to match QN9090. QN9090 has no ALIAS register. 34 * - Added "SHA_ClkInit" "SHA_ClkInit" 35 * - Version 2.1.1 36 * - MISRA C-2012 issue fixed: rule 10.3, 10.4, 11.9, 14.4, 16.4 and 17.7. 37 * - Version 2.2.0 38 * - Support MEMADDR pseudo DMA for loading input data in SHA_Update function (LPCXpresso54018 and LPCXpresso54628). 39 * - Version 2.2.1 40 * - MISRA C-2012 issue fix. 41 * - Version 2.2.2 42 * Modified SHA_Finish function. While using pseudo DMA with maximum optimization, compiler optimize out condition. 43 * Which caused block in this function and did not check state, which has been set in interrupt. 44 * - Version 2.3.0 45 * Modified SHA_Update to use blocking version of AHB Master mode when its available on chip. Added 46 *SHA_UpdateNonBlocking() function which uses nonblocking AHB Master mode. Fixed incorrect calculation of SHA when 47 *calling SHA_Update multiple times when is CPU used to load data. Added Reset into SHA_ClkInit and SHA_ClkDeinit 48 *function. 49 * - Version 2.3.1 50 * Modified sha_process_message_data_master() to ensure that MEMCTRL will be written within 64 cycles of writing last 51 *word to INDATA as is mentioned in errata, even with different optimization levels. 52 * - Version 2.3.2 53 * Add -O2 optimization for GCC to sha_process_message_data_master(), because without it the function hangs under some 54 *conditions. 55 */ 56 #define FSL_SHA_DRIVER_VERSION (MAKE_VERSION(2, 3, 2)) 57 /*! @} */ 58 59 /*! Supported cryptographic block cipher functions for HASH creation */ 60 typedef enum _sha_algo_t 61 { 62 kSHA_Sha1, /*!< SHA_1 */ 63 kSHA_Sha256, /*!< SHA_256 */ 64 } sha_algo_t; 65 66 /*! @brief SHA Context size. */ 67 #define SHA_CTX_SIZE 22U 68 69 /*! @brief Storage type used to save hash context. */ 70 typedef struct _sha_ctx_t 71 { 72 uint32_t x[SHA_CTX_SIZE]; 73 } sha_ctx_t; 74 75 /*! @brief background hash callback function. */ 76 typedef void (*sha_callback_t)(SHA_Type *base, sha_ctx_t *ctx, status_t status, void *userData); 77 78 /******************************************************************************* 79 * API 80 *******************************************************************************/ 81 82 #if defined(__cplusplus) 83 extern "C" { 84 #endif /* __cplusplus */ 85 86 /*! 87 * @name SHA Functional Operation 88 * @{ 89 */ 90 91 /*! 92 * @addtogroup sha_algorithm_level_api 93 * @{ 94 */ 95 /*! 96 * @brief Initialize HASH context 97 * 98 * This function initializes new hash context. 99 * 100 * @param base SHA peripheral base address 101 * @param[out] ctx Output hash context 102 * @param algo Underlaying algorithm to use for hash computation. Either SHA-1 or SHA-256. 103 * @return Status of initialization 104 */ 105 status_t SHA_Init(SHA_Type *base, sha_ctx_t *ctx, sha_algo_t algo); 106 107 /*! 108 * @brief Add data to current HASH 109 * 110 * Add data to current HASH. This can be called repeatedly with an arbitrary amount of data to be 111 * hashed. 112 * 113 * @param base SHA peripheral base address 114 * @param[in,out] ctx HASH context 115 * @param message Input message 116 * @param messageSize Size of input message in bytes 117 * @return Status of the hash update operation 118 */ 119 status_t SHA_Update(SHA_Type *base, sha_ctx_t *ctx, const uint8_t *message, size_t messageSize); 120 121 /*! 122 * @brief Finalize hashing 123 * 124 * Outputs the final hash and erases the context. SHA-1 or SHA-256 padding bits are automatically added by this 125 * function. 126 * 127 * @param base SHA peripheral base address 128 * @param[in,out] ctx HASH context 129 * @param[out] output Output hash data 130 * @param[in,out] outputSize On input, determines the size of bytes of the output array. On output, tells how many bytes 131 * have been written to output. 132 * @return Status of the hash finish operation 133 */ 134 status_t SHA_Finish(SHA_Type *base, sha_ctx_t *ctx, uint8_t *output, size_t *outputSize); 135 136 #if defined(FSL_FEATURE_SHA_HAS_MEMADDR_DMA) && (FSL_FEATURE_SHA_HAS_MEMADDR_DMA > 0) 137 /*! 138 * @brief Initializes the SHA handle for background hashing. 139 * 140 * This function initializes the hash context for background hashing 141 * (Non-blocking) APIs. This is less typical interface to hash function, but can be used 142 * for parallel processing, when main CPU has something else to do. 143 * Example is digital signature RSASSA-PKCS1-V1_5-VERIFY((n,e),M,S) algorithm, where 144 * background hashing of M can be started, then CPU can compute S^e mod n 145 * (in parallel with background hashing) and once the digest becomes available, 146 * CPU can proceed to comparison of EM with EM'. 147 * 148 * @param base SHA peripheral base address. 149 * @param[out] ctx Hash context. 150 * @param callback Callback function. 151 * @param userData User data (to be passed as an argument to callback function, once callback is invoked from isr). 152 */ 153 void SHA_SetCallback(SHA_Type *base, sha_ctx_t *ctx, sha_callback_t callback, void *userData); 154 155 /*! 156 * @brief Create running hash on given data. 157 * 158 * Configures the SHA to compute new running hash as AHB master 159 * and returns immediately. SHA AHB Master mode supports only aligned \p input 160 * address and can be called only once per continuous block of data. Every call to this function 161 * must be preceded with SHA_Init() and finished with _SHA_Finish(). 162 * Once callback function is invoked by SHA isr, it should set a flag 163 * for the main application to finalize the hashing (padding) and to read out the final digest 164 * by calling SHA_Finish(). 165 * 166 * @param base SHA peripheral base address 167 * @param ctx Specifies callback. Last incomplete 512-bit block of the input is copied into clear buffer for padding. 168 * @param input 32-bit word aligned pointer to Input data. 169 * @param inputSize Size of input data in bytes (must be word aligned) 170 * @return Status of the hash update operation. 171 */ 172 status_t SHA_UpdateNonBlocking(SHA_Type *base, sha_ctx_t *ctx, const uint8_t *input, size_t inputSize); 173 #endif /* defined(FSL_FEATURE_SHA_HAS_MEMADDR_DMA) && (FSL_FEATURE_SHA_HAS_MEMADDR_DMA > 0) */ 174 175 /*! 176 * @brief Start SHA clock 177 * 178 * Start SHA clock 179 * 180 * @param base SHA peripheral base address 181 * 182 */ 183 void SHA_ClkInit(SHA_Type *base); 184 185 /*! 186 * @brief Stop SHA clock 187 * 188 * Stop SHA clock 189 * 190 * @param base SHA peripheral base address 191 * 192 */ 193 void SHA_ClkDeinit(SHA_Type *base); 194 195 /*! 196 *@} 197 */ /* sha_algorithm_level_api */ 198 199 #if defined(__cplusplus) 200 } 201 #endif /* __cplusplus */ 202 203 /*! @}*/ 204 /*! @}*/ /* end of group sha */ 205 206 #endif /* FSL_SHA_H_ */ 207
