1 /***************************************************************************//** 2 * \file cy_cryptolite.h 3 * \version 2.50 4 * 5 * \brief 6 * This file provides interface header 7 * for the Cryptolite PDL driver. 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 * \addtogroup group_cryptolite 29 * \{ 30 * \note IP Supported: CRYPTOLITE 31 * \note Availability of Cryptolite Algorithms will be chip specific, Refer to individual API for availability. 32 * \note Device Categories: CAT1B. Please refer <a href="usergroup1.html">Device Catalog</a>. 33 * 34 * The PDL Cryptolite driver provides a public API to perform hardware accelerated cryptographic calculations. 35 * 36 * The functions and other declarations used in this driver are in cy_cryptolite.h. 37 * You can also include cy_pdl.h to get access to all functions and declarations in the PDL. 38 * 39 * The Cryptolite driver supports AES (128bits), SHA-256, HMAC-SHA256, TRNG, RSA and ECDSA. 40 * 41 * \section group_cryptolite_configuration_considerations Configuration Considerations 42 * 43 * User can enable/disable cryptographic functionality based on the project 44 * requirements. To do so, create a configuration header file to configure cryptographic 45 * functionalities and define a macro CY_CRYPTOLITE_USER_CONFIG_FILE with configuration 46 * header file name and add to project environment. If CY_CRYPTOLITE_USER_CONFIG_FILE macro 47 * is not defined in project environment, firmware will enable all available 48 * cryptographic functionalities. 49 * 50 *Firmware sets up a cryptographic operation by passing in the required data as parameters in the function calls. 51 * 52 * All Cryptolite function require a context. A context is a data 53 * structure that the driver uses for its operations. Firmware declares a 54 * context (allocates memory) but does not write or read the values in that 55 * context. In effect, the context is a scratch pad you provide to the driver. 56 * The driver uses the context to store and manipulate data during cryptographic 57 * operations. The Cryptolite driver header file declare all the required structures 58 * for context. 59 * 60 * 61 * \section group_cryptolite_sha256_definitions Definitions 62 * 63 * <table class="doxtable"> 64 * <tr> 65 * <th>Term</th> 66 * <th>Definition</th> 67 * </tr> 68 * 69 * <tr> 70 * <td>Secure Hash Algorithm (SHA)</td> 71 * <td>A cryptographic hash function. 72 * This function takes a message of an arbitrary length and reduces it to a 73 * fixed-length residue or message digest after performing a series of 74 * mathematically defined operations that practically guarantee that any 75 * change in the message will change the hash value. It is used for message 76 * authentication by transmitting a message with a hash value appended to it 77 * and recalculating the message hash value using the same algorithm at the 78 * recipient's end. If the hashes differ, then the message is corrupted. 79 * For more information see [Secure Hash standard description] 80 * (https://csrc.nist.gov/csrc/media/publications/fips/180/2/archive/2002-08-01/documents/fips180-2.pdf). 81 * </td> 82 * </tr> 83 * <tr> 84 * <td>Plaintext</td> 85 * <td>An unencrypted message</td> 86 * </tr> 87 * 88 * <tr> 89 * <td>Ciphertext</td> 90 * <td>An encrypted message</td> 91 * </tr> 92 * 93 * <tr> 94 * <td>Block Cipher</td> 95 * <td>An encryption function for fixed-size blocks of data. 96 * This function takes a fixed-size key and a block of plaintext data from 97 * the message and encrypts it to generate ciphertext. Block ciphers are 98 * reversible. The function performed on a block of encrypted data will 99 * decrypt that data.</td> 100 * </tr> 101 * 102 * <tr> 103 * <td>Block Cipher Mode</td> 104 * <td>A mode of encrypting a message using block ciphers for messages of an 105 * arbitrary length. The message is padded so that its length is an integer 106 * multiple of the block size. ECB (Electronic Code Book), CBC (Cipher Block 107 * Chaining), and CFB (Cipher Feedback) are all modes of using block ciphers 108 * to create an encrypted message of an arbitrary length. 109 * </td> 110 * </tr> 111 * <tr> 112 * <td>Advanced Encryption Standard (AES)</td> 113 * <td>The [AES standard] (https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.197.pdf) 114 * specifies the Rijndael algorithm, a symmetric block 115 * cipher that can process 128-bit data blocks, using cipher keys with 116 * 128-, 192-, and 256-bit lengths. Rijndael was designed to handle 117 * additional block sizes and key lengths. However, they are not adopted in 118 * this standard. AES is also used for message authentication. 119 * </td> 120 * </tr> 121 * <tr> 122 * <td>Message Authentication Code (MAC)</td> 123 * <td>MACs are used to verify that a received message has not been altered. 124 * This is done by first computing a MAC value at the sender's end and 125 * appending it to the transmitted message. When the message is received, 126 * the MAC is computed again and checked against the MAC value transmitted 127 * with the message. If they do not match, the message has been altered. 128 * Either a Hash algorithm (such as SHA) or a block cipher (such as AES) can 129 * be used to produce the MAC value. Keyed MAC schemes use a Secret Key 130 * along with the message, thus the Key value must be known to be able to 131 * compute the MAC value.</td> 132 * </tr> 133 * 134 * <tr> 135 * <td>Hash Message Authentication Code (HMAC)</td> 136 * <td>A specific type of message authentication code (MAC) that involves a 137 * cryptographic hash function and a secret cryptographic key. 138 * It computes the MAC value using a Hash algorithm. 139 * For more information see [The Keyed-Hash Message Authentication Code standard] 140 * (https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf) 141 * </td> 142 * </tr> 143 * <tr> 144 * <td>True Random Number Generator (TRNG)</td> 145 * <td>A block that generates a number that is statistically random and based 146 * on some physical random variation. The number cannot be duplicated by 147 * running the process again.</td> 148 * </tr> 149 * 150 * <tr> 151 * <td>Symmetric Key Cryptography</td> 152 * <td>Uses a common, known key to encrypt and decrypt messages (a shared 153 * secret between sender and receiver). An efficient method used for 154 * encrypting and decrypting messages after the authenticity of the other 155 * party has been established. AES is well-known symmetric cryptography methods.</td> 156 * </tr> 157 * 158 * <tr> 159 * <td>Asymmetric Key Cryptography</td> 160 * <td>Also referred to as Public Key encryption. To receive a message, 161 * you publish a very large public key (up to 4096 bits currently). The 162 * public key is described by the pair (n, e) where n is a product of 163 * two randomly chosen primes p and q. The exponent e is a random integer 164 * 1 < e < Q where Q = (p-1) (q-1). The private key d is uniquely defined 165 * by the integer 1 < d < Q so that ed congruent with 1 (mod Q ). To send 166 * a message to the publisher of the public key, you encrypt the message 167 * with the public key. This message can now be decrypted only with the 168 * private key. The message is now sent over any channel to the recipient 169 * who can decrypt it with the private (secret) key. The same process is 170 * used to send messages to the sender of the original message. The 171 * asymmetric cryptography relies on the mathematical impracticality 172 * (usually related to the processing power available at any given time) 173 * of factoring the keys. 174 * </td> 175 * </tr> 176 * 177 * </table> 178 * 179 * \section group_cryptolite_changelog Changelog 180 * <table class="doxtable"> 181 * <tr><th>Version</th><th>Changes</th><th>Reason for Change</th></tr> 182 * <tr> 183 * <td>2.50</td> 184 * <td> 185 * <ul> 186 * <li>Support for AES-CCM, AES-CMAC, AES-CBC-MAC & AES multistage for modes ECB, CBC, CFB, CTR added.</li> 187 * <li>Support for HKDF added.</li> 188 * <li>Support for ECC key pair generation & ECDSA Sign added .</li> 189 * </ul> 190 * </td> 191 * <td></td> 192 * </tr> 193 * <tr> 194 * <td>2.40</td> 195 * <td>Updated value of CY_CRYPTOLITE_DEF_TRNG_GARO macro.</td> 196 * <td>Usability enhancement.</td> 197 * </tr> 198 * <tr> 199 * <td>2.30</td> 200 * <td>Updated APIs \ref Cy_Cryptolite_ECC_VerifyHash and \ref Cy_Cryptolite_Aes_Ctr.</td> 201 * <td>Support for ECDSA verify for HASHZERO message added and MISRA 2012 violation fix</td> 202 * </tr> 203 * <tr> 204 * <td>2.20</td> 205 * <td> 206 * <ul> 207 * <li>Updated TRNG default config.</li> 208 * </ul> 209 * </td> 210 * <td></td> 211 * </tr> 212 * <tr> 213 * <td>2.10</td> 214 * <td> 215 * <ul> 216 * <li>Added HMAC-SHA256 & AES(128 bit) support.</li> 217 * <li>Added TRNG support.</li> 218 * <li>Added RSA signature verification support upto 4096 bit</li> 219 * <li>Added ECDSA signature verification support for SECP256R1 & SECP384R1</li> 220 * </ul> 221 * </td> 222 * <td></td> 223 * </tr> 224 * <tr> 225 * <td>2.0</td> 226 * <td>Renamed the sha256 context structure from cy_stc_cryptolite_context_sha_t to cy_stc_cryptolite_context_sha256_t </td> 227 * <td></td> 228 * </tr> 229 * <tr> 230 * <td>1.0</td> 231 * <td>Initial Version</td> 232 * <td></td> 233 * </tr> 234 * </table> 235 * \defgroup group_cryptolite_lld_sha Hash operations (SHA) 236 * \{ 237 * \defgroup group_cryptolite_lld_sha_functions Functions 238 * \} 239 * \defgroup group_cryptolite_lld_mac Message Authentication Code (HMAC, CMAC) 240 * \{ 241 * \defgroup group_cryptolite_lld_mac_functions Functions 242 * \} 243 * \defgroup group_cryptolite_lld_aes Symmetric Key Algorithm (AES) 244 * \{ 245 * \defgroup group_cryptolite_lld_aes_functions Functions 246 * \} 247 * \defgroup group_cryptolite_lld_kdf Key Derivative Function (HKDF) 248 * \{ 249 * \defgroup group_cryptolite_lld_kdf_functions Functions 250 * \} 251 * \defgroup group_cryptolite_lld_asymmetric Asymmetric Key Algorithm (RSA,ECP,ECDSA) 252 * \{ 253 * \defgroup group_cryptolite_lld_asymmetric_functions Functions 254 * \} 255 * \defgroup group_cryptolite_lld_keygen Key Generation (ECP) 256 * \{ 257 * \defgroup group_cryptolite_lld_keygen_functions Functions 258 * \} 259 * \defgroup group_cryptolite_lld_random_number Random Number Generation(TRNG) 260 * \{ 261 * \defgroup group_cryptolite_lld_rng_functions Functions 262 * \} 263 * \defgroup group_cryptolite_lld_vu Vector Unit (VU) 264 * \{ 265 * \defgroup group_cryptolite_lld_vu_functions Functions 266 * \} 267 * \defgroup group_cryptolite_data_structures Common Data Structures 268 * \defgroup group_cryptolite_enums Common Enumerated Types 269 * \defgroup group_cryptolite_macros Macros 270 */ 271 272 #if !defined (CY_CRYPTOLITE_H) 273 #define CY_CRYPTOLITE_H 274 275 #include "cy_device.h" 276 277 #if defined (CY_IP_MXCRYPTOLITE) 278 279 #include "cy_cryptolite_sha256.h" 280 #include "cy_cryptolite_hmac.h" 281 #include "cy_cryptolite_ecdsa.h" 282 #include "cy_cryptolite_rsa.h" 283 #include "cy_cryptolite_trng.h" 284 #include "cy_cryptolite_aes.h" 285 #include "cy_cryptolite_aes_ccm.h" 286 #include "cy_cryptolite_ecc_key_gen.h" 287 #include "cy_cryptolite_hkdf.h" 288 #include "cy_cryptolite_cmac.h" 289 290 #endif /* CY_IP_MXCRYPTOLITE */ 291 292 #endif /* #if !defined (CY_CRYPTOLITE_H) */ 293 /** \} group_cryptolite */ 294 295 /* [] END OF FILE */ 296
