1 /***************************************************************************//** 2 * \file cy_crypto_core.h 3 * \version 2.120 4 * 5 * \brief 6 * This file provides common constants and parameters 7 * for the Crypto driver core interface. 8 * 9 ******************************************************************************** 10 * \copyright 11 * Copyright (c) (2020-2022), Cypress Semiconductor Corporation (an Infineon company) or 12 * an affiliate of Cypress Semiconductor Corporation. 13 * SPDX-License-Identifier: Apache-2.0 14 * 15 * Licensed under the Apache License, Version 2.0 (the "License"); 16 * you may not use this file except in compliance with the License. 17 * You may obtain a copy of the License at 18 * 19 * http://www.apache.org/licenses/LICENSE-2.0 20 * 21 * Unless required by applicable law or agreed to in writing, software 22 * distributed under the License is distributed on an "AS IS" BASIS, 23 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 24 * See the License for the specific language governing permissions and 25 * limitations under the License. 26 *******************************************************************************/ 27 28 /** 29 * \addtogroup group_crypto_lld_api 30 * \{ 31 * Use the low-level API for direct access to the Crypto hardware. 32 * 33 * The functions and other declarations used in this part of the driver are in 34 * cy_crypto_core.h. You can also include cy_pdl.h to get 35 * access to all functions and declarations in the PDL. 36 * 37 * Firmware initializes and starts the Crypto operations. The firmware then 38 * provides the configuration data required for the desired cryptographic 39 * technique. 40 * 41 * \section group_crypto_lld_common_use_cases Common Use Cases 42 * 43 * \subsection group_crypto_lld_crypto_enable Crypto Hardware Enable 44 * 45 * Use \ref Cy_Crypto_Core_Enable to enable the Crypto IP block, After this 46 * call, the Crypto driver is ready to execute crypto functions 47 * 48 * Code example: 49 * \snippet crypto/snippet/main.c snippet_myCryptoCoreStartCryptoUse 50 * 51 * \subsection group_crypto_lld_crypto_disable Crypto Hardware Disable 52 * 53 * Use \ref Cy_Crypto_Core_Disable to disable the Crypto IP block and call 54 * \ref Cy_Crypto_Core_ClearVuRegisters to clear whole register file, After this 55 * call, No crypto function should be executed 56 * 57 * Code example: 58 * \snippet crypto/snippet/main.c snippet_myCryptoCoreStopCryptoUse 59 * 60 * \subsection group_crypto_lld_Use_TDES TDES encryption 61 * 62 * To encrypt a message using the TDES algorithm: 63 * 64 * - Place three DES keys into an array, 65 * - Call \ref Cy_Crypto_Core_Tdes with required parameters, including the array 66 * of keys 67 * 68 * Code example: 69 * \snippet crypto/snippet/main.c snippet_myCryptoCoreTdesUse 70 * 71 * \subsection group_crypto_lld_Use_DES DES encryption 72 * 73 * To encrypt a message using the DES algorithm: 74 * - Place DES key into an array, 75 * - Call \ref Cy_Crypto_Core_Des with required parameters, including the key 76 * array 77 * 78 * Code example: 79 * \snippet crypto/snippet/main.c snippet_myCryptoCoreDesUse 80 * 81 * \subsection group_crypto_lld_Use_AES AES encryption 82 * 83 * The Crypto driver provides a four AES encryption algorithms (ECB, CBC, CFB 84 * and CTR) that are used similarly. 85 * 86 * To encrypt a message using AES ECB algorithm (as example): 87 * - Place AES key into array of appropriate size 88 * - Use \ref Cy_Crypto_Core_Aes_Init to configure the operation 89 * - Call \ref Cy_Crypto_Core_Aes_Ecb (\ref Cy_Crypto_Core_Aes_Cbc, 90 * \ref Cy_Crypto_Core_Aes_Cfb or \ref Cy_Crypto_Core_Aes_Ctr) with appropriate 91 * parameters to make an operation 92 * 93 * Code example: 94 * \snippet crypto/snippet/main.c snippet_myCryptoCoreAesEcbUse 95 * 96 * \subsection group_crypto_lld_Use_CRC CRC Calculation 97 * 98 * To calculate CRC of a data image: 99 * - Use \ref Cy_Crypto_Core_Crc_CalcInit to set parameters for selected CRC mode, 100 * - Call \ref Cy_Crypto_Core_Crc_Calc to calculate CRC for a data image. 101 * 102 * Code example: 103 * \snippet crypto/snippet/main.c snippet_myCryptoCoreCrcUse 104 * 105 * \subsection group_crypto_lld_Use_SHA SHA digest calculation 106 * 107 * To calculate a SHA digest of a message: 108 * - Call \ref Cy_Crypto_Core_Sha with appropriate parameters to make an 109 * operation 110 * 111 * Code example: 112 * \snippet crypto/snippet/main.c snippet_myCryptoCoreSha256Use 113 * 114 * \subsection group_crypto_lld_Use_RSA_VER RSA signature verification 115 * 116 * To verify the RSA signature of the data image: 117 * - Fill RSA public key structure by RSA public key data 118 * - Use \ref Cy_Crypto_Core_Sha to calculate SHA digest of the data image 119 * - Use \ref Cy_Crypto_Core_Rsa_Proc to decrypt present encrypted signature 120 * - Use \ref Cy_Crypto_Core_Rsa_Verify to verify the decrypted signature with 121 * calculated SHA digest 122 * 123 * Code example: 124 * \snippet crypto/snippet/main.c snippet_myCryptoCoreRsaVerUse 125 * 126 * \section group_crypto_lld_rsa_considerations RSA Usage Considerations 127 * 128 * General RSA encryption and decryption is supported. 129 * \ref Cy_Crypto_Core_Rsa_Proc encrypts or decrypts data based on the parameters 130 * passed to the function. If you pass in plain text and a public key, the output 131 * is encrypted (cipher text). If you pass in cipher text and a private key, the 132 * output is decrypted (plain text). 133 * 134 * One parameter for this function call is a structure that defines the key: 135 * cy_stc_crypto_rsa_pub_key_t. The four modulus and exponent fields are 136 * mandatory. They represent the data for either the public or private key as 137 * appropriate. 138 * 139 * \note The <b>modulus</b> and <b>exponent</b> values in the 140 * \ref cy_stc_crypto_rsa_pub_key_t must be in little-endian order.<br> 141 * Use the \ref Cy_Crypto_Core_InvertEndianness function to convert to or from 142 * little-endian order. 143 * 144 * The remaining fields represent three pre-calculated coefficients that can 145 * reduce execution time by up to 5x. The fields are: coefficient for Barrett 146 * reduction, binary inverse of the modulus, and the result of 147 * (2^moduloLength mod modulo). These fields are optional, and can be set to NULL. 148 * 149 * Calculate these coefficients with \ref Cy_Crypto_Core_Rsa_Coef. 150 * Pass them in the address of the key structure with the modulus and exponent 151 * values for the key. The function returns the coefficients for the key in the 152 * key structure, replacing any previous values. 153 * 154 * The RSA functionality also implements functions to decrypt a signature using 155 * a public key. This signature must follow the RSASSA-PKCS-v1_5 standard. 156 * The signature must contain a SHA digest (hash). 157 * MD2, MD4, and MD5 message digests are not supported. 158 * 159 * An encrypted signature is stored as big-endian data. It must be inverted for 160 * RSA processing. To use the provided signature decryption, firmware must 161 * -# Calculate the SHA digest of the data to be verified with 162 * \ref Cy_Crypto_Core_Sha. 163 * -# Ensure that the RSA signature is in little-endian format. 164 * Use \ref Cy_Crypto_Core_InvertEndianness. 165 * -# Decrypt the RSA signature with a public key, by calling 166 * \ref Cy_Crypto_Core_Rsa_Proc. 167 * -# Invert the byte order of the output, to return to big-endian format. 168 * Use \ref Cy_Crypto_Core_InvertEndianness. 169 * -# Call \ref Cy_Crypto_Core_Rsa_Verify (which requires data in big-endian format). 170 * 171 * \subsection group_crypto_lld_Use_CMAC CMAC calculation 172 * 173 * To calculate CMAC of a message: 174 * - Place AES key into array of appropriate size 175 * - Call \ref Cy_Crypto_Core_Cmac with appropriate parameters to make an 176 * operation 177 * 178 * Code example: 179 * \snippet crypto/snippet/main.c snippet_myCryptoCoreCmacUse 180 * 181 * \subsection group_crypto_lld_Use_HMAC HMAC calculation 182 * 183 * To calculate HMAC of a message: 184 * - Place HMAC key into array of appropriate size 185 * - Call \ref Cy_Crypto_Core_Hmac with appropriate parameters to make an 186 * operation 187 * 188 * Code example: 189 * \snippet crypto/snippet/main.c snippet_myCryptoCoreHmacUse 190 * 191 * \subsection group_crypto_lld_Use_PRNG Pseudo Random Number Generation 192 * 193 * To generate a pseudo random number: 194 * - Use \ref Cy_Crypto_Core_Prng_Init to set required parameters, 195 * - Call \ref Cy_Crypto_Core_Prng. 196 * 197 * Code example: 198 * \snippet crypto/snippet/main.c snippet_myCryptoCorePrngUse 199 * 200 * \subsection group_crypto_lld_Use_TRNG True Random Number Generation 201 * 202 * To generate a true random number: 203 * - Call \ref Cy_Crypto_Core_Trng with needed parameters. 204 * 205 * Code example: 206 * \snippet crypto/snippet/main.c snippet_myCryptoCoreTrngUse 207 * 208 * \defgroup group_crypto_lld_hw Control and Status 209 * \{ 210 * \defgroup group_crypto_lld_hw_functions Functions 211 * \} 212 * \defgroup group_crypto_lld_symmetric Symmetric Key Algorithms (AES, GCM, DES, TDES) 213 * \{ 214 * \defgroup group_crypto_lld_symmetric_functions Functions 215 * \} 216 * \defgroup group_crypto_lld_asymmetric Asymmetric Key Algorithms (RSA, ECP, ECDSA, EDDSA) 217 * \{ 218 * \defgroup group_crypto_lld_asymmetric_functions Functions 219 * \defgroup group_crypto_lld_asymmetric_enums Enumerated Types 220 * \} 221 * \defgroup group_crypto_lld_sha Hash Operations (SHA) 222 * \{ 223 * \defgroup group_crypto_lld_sha_functions Functions 224 * \} 225 * \defgroup group_crypto_lld_mac Message Authentication Code (CMAC, HMAC) 226 * \{ 227 * \defgroup group_crypto_lld_mac_functions Functions 228 * \} 229 * \defgroup group_crypto_lld_kdf Key Derivative Function (HKDF) 230 * \{ 231 * \defgroup group_crypto_lld_kdf_functions Functions 232 * \} 233 * \defgroup group_crypto_lld_crc Cyclic Redundancy Code (CRC) 234 * \{ 235 * \defgroup group_crypto_lld_crc_functions Functions 236 * \} 237 * \defgroup group_crypto_lld_rng Random Number Generation (TRNG, PRNG) 238 * \{ 239 * \defgroup group_crypto_lld_rng_functions Functions 240 * \} 241 * \defgroup group_crypto_lld_vu Vector Unit (VU) 242 * \{ 243 * \defgroup group_crypto_lld_vu_functions Functions 244 * \} 245 * \defgroup group_crypto_lld_mem Memory Streaming Functions 246 * \{ 247 * \defgroup group_crypto_lld_mem_functions Functions 248 * \} 249 * \} */ 250 251 #if !defined (CY_CRYPTO_CORE_H) 252 #define CY_CRYPTO_CORE_H 253 254 #include "cy_crypto_core_aes.h" 255 #include "cy_crypto_core_crc.h" 256 #include "cy_crypto_core_cmac.h" 257 #include "cy_crypto_core_des.h" 258 #include "cy_crypto_core_ecc.h" 259 #include "cy_crypto_core_ecc_nist_p.h" 260 #include "cy_crypto_core_hmac.h" 261 #include "cy_crypto_core_hw.h" 262 #include "cy_crypto_core_prng.h" 263 #include "cy_crypto_core_mem.h" 264 #include "cy_crypto_core_rsa.h" 265 #include "cy_crypto_core_sha.h" 266 #include "cy_crypto_core_trng.h" 267 #include "cy_crypto_core_vu.h" 268 #include "cy_crypto_core_hkdf.h" 269 #endif /* #if !defined (CY_CRYPTO_CORE_H) */ 270 271 /* [] END OF FILE */ 272
