1 /***************************************************************************//** 2 * \file cy_cryptolite.h 3 * \version 2.30 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 * Note: Cryptolite works only with SAHB mapped address, User must map any CBUS mapped 61 * address to SAHB address before using the API. 62 * 63 * \section group_cryptolite_sha256_definitions Definitions 64 * 65 * <table class="doxtable"> 66 * <tr> 67 * <th>Term</th> 68 * <th>Definition</th> 69 * </tr> 70 * 71 * <tr> 72 * <td>Secure Hash Algorithm (SHA)</td> 73 * <td>A cryptographic hash function. 74 * This function takes a message of an arbitrary length and reduces it to a 75 * fixed-length residue or message digest after performing a series of 76 * mathematically defined operations that practically guarantee that any 77 * change in the message will change the hash value. It is used for message 78 * authentication by transmitting a message with a hash value appended to it 79 * and recalculating the message hash value using the same algorithm at the 80 * recipient's end. If the hashes differ, then the message is corrupted. 81 * For more information see [Secure Hash standard description] 82 * (https://csrc.nist.gov/csrc/media/publications/fips/180/2/archive/2002-08-01/documents/fips180-2.pdf). 83 * </td> 84 * </tr> 85 * <tr> 86 * <td>Plaintext</td> 87 * <td>An unencrypted message</td> 88 * </tr> 89 * 90 * <tr> 91 * <td>Ciphertext</td> 92 * <td>An encrypted message</td> 93 * </tr> 94 * 95 * <tr> 96 * <td>Block Cipher</td> 97 * <td>An encryption function for fixed-size blocks of data. 98 * This function takes a fixed-size key and a block of plaintext data from 99 * the message and encrypts it to generate ciphertext. Block ciphers are 100 * reversible. The function performed on a block of encrypted data will 101 * decrypt that data.</td> 102 * </tr> 103 * 104 * <tr> 105 * <td>Block Cipher Mode</td> 106 * <td>A mode of encrypting a message using block ciphers for messages of an 107 * arbitrary length. The message is padded so that its length is an integer 108 * multiple of the block size. ECB (Electronic Code Book), CBC (Cipher Block 109 * Chaining), and CFB (Cipher Feedback) are all modes of using block ciphers 110 * to create an encrypted message of an arbitrary length. 111 * </td> 112 * </tr> 113 * <tr> 114 * <td>Advanced Encryption Standard (AES)</td> 115 * <td>The [AES standard] (https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.197.pdf) 116 * specifies the Rijndael algorithm, a symmetric block 117 * cipher that can process 128-bit data blocks, using cipher keys with 118 * 128-, 192-, and 256-bit lengths. Rijndael was designed to handle 119 * additional block sizes and key lengths. However, they are not adopted in 120 * this standard. AES is also used for message authentication. 121 * </td> 122 * </tr> 123 * <tr> 124 * <td>Message Authentication Code (MAC)</td> 125 * <td>MACs are used to verify that a received message has not been altered. 126 * This is done by first computing a MAC value at the sender's end and 127 * appending it to the transmitted message. When the message is received, 128 * the MAC is computed again and checked against the MAC value transmitted 129 * with the message. If they do not match, the message has been altered. 130 * Either a Hash algorithm (such as SHA) or a block cipher (such as AES) can 131 * be used to produce the MAC value. Keyed MAC schemes use a Secret Key 132 * along with the message, thus the Key value must be known to be able to 133 * compute the MAC value.</td> 134 * </tr> 135 * 136 * <tr> 137 * <td>Hash Message Authentication Code (HMAC)</td> 138 * <td>A specific type of message authentication code (MAC) that involves a 139 * cryptographic hash function and a secret cryptographic key. 140 * It computes the MAC value using a Hash algorithm. 141 * For more information see [The Keyed-Hash Message Authentication Code standard] 142 * (https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf) 143 * </td> 144 * </tr> 145 * <tr> 146 * <td>True Random Number Generator (TRNG)</td> 147 * <td>A block that generates a number that is statistically random and based 148 * on some physical random variation. The number cannot be duplicated by 149 * running the process again.</td> 150 * </tr> 151 * 152 * <tr> 153 * <td>Symmetric Key Cryptography</td> 154 * <td>Uses a common, known key to encrypt and decrypt messages (a shared 155 * secret between sender and receiver). An efficient method used for 156 * encrypting and decrypting messages after the authenticity of the other 157 * party has been established. AES is well-known symmetric cryptography methods.</td> 158 * </tr> 159 * 160 * <tr> 161 * <td>Asymmetric Key Cryptography</td> 162 * <td>Also referred to as Public Key encryption. To receive a message, 163 * you publish a very large public key (up to 4096 bits currently). The 164 * public key is described by the pair (n, e) where n is a product of 165 * two randomly chosen primes p and q. The exponent e is a random integer 166 * 1 < e < Q where Q = (p-1) (q-1). The private key d is uniquely defined 167 * by the integer 1 < d < Q so that ed congruent with 1 (mod Q ). To send 168 * a message to the publisher of the public key, you encrypt the message 169 * with the public key. This message can now be decrypted only with the 170 * private key. The message is now sent over any channel to the recipient 171 * who can decrypt it with the private (secret) key. The same process is 172 * used to send messages to the sender of the original message. The 173 * asymmetric cryptography relies on the mathematical impracticality 174 * (usually related to the processing power available at any given time) 175 * of factoring the keys. 176 * </td> 177 * </tr> 178 * 179 * </table> 180 * 181 * \section group_cryptolite_changelog Changelog 182 * <table class="doxtable"> 183 * <tr><th>Version</th><th>Changes</th><th>Reason for Change</th></tr> 184 * <tr> 185 * <td>2.30</td> 186 * <td>Updated APIs \ref Cy_Cryptolite_ECC_VerifyHash and \ref Cy_Cryptolite_Aes_Ctr.</td> 187 * <td>Support for ECDSA verify for HASHZERO message added and MISRA 2012 violation fix</td> 188 * </tr> 189 * <tr> 190 * <td>2.20</td> 191 * <td> 192 * <ul> 193 * <li>Updated TRNG default config.</li> 194 * </ul> 195 * </td> 196 * <td></td> 197 * </tr> 198 * <tr> 199 * <td>2.10</td> 200 * <td> 201 * <ul> 202 * <li>Added HMAC-SHA256 & AES(128 bit) support.</li> 203 * <li>Added TRNG support.</li> 204 * <li>Added RSA signature verification support upto 4096 bit</li> 205 * <li>Added ECDSA signature verification support for SECP256R1 & SECP384R1</li> 206 * </ul> 207 * </td> 208 * <td></td> 209 * </tr> 210 * <tr> 211 * <td>2.0</td> 212 * <td>Renamed the sha256 context structure from cy_stc_cryptolite_context_sha_t to cy_stc_cryptolite_context_sha256_t </td> 213 * <td></td> 214 * </tr> 215 * <tr> 216 * <td>1.0</td> 217 * <td>Initial Version</td> 218 * <td></td> 219 * </tr> 220 * </table> 221 * \defgroup group_cryptolite_lld_sha Hash operations (SHA) 222 * \{ 223 * \defgroup group_cryptolite_lld_sha_functions Functions 224 * \} 225 * \defgroup group_cryptolite_lld_hmac Message Authentication Code (HMAC) 226 * \{ 227 * \defgroup group_cryptolite_lld_hmac_functions Functions 228 * \} 229 * \defgroup group_cryptolite_lld_aes Symmetric Key Algorithm (AES) 230 * \{ 231 * \defgroup group_cryptolite_lld_aes_functions Functions 232 * \} 233 * \defgroup group_cryptolite_lld_asymmetric Asymmetric Key Algorithm (RSA,ECP,ECDSA) 234 * \{ 235 * \defgroup group_cryptolite_lld_asymmetric_functions Functions 236 * \} 237 * \defgroup group_cryptolite_lld_random_number Random Number Generation(TRNG) 238 * \{ 239 * \defgroup group_cryptolite_lld_rng_functions Functions 240 * \} 241 * \defgroup group_cryptolite_lld_vu Vector Unit (VU) 242 * \{ 243 * \defgroup group_cryptolite_lld_vu_functions Functions 244 * \} 245 * \defgroup group_cryptolite_data_structures Common Data Structures 246 * \defgroup group_cryptolite_enums Common Enumerated Types 247 * \defgroup group_cryptolite_macros Macros 248 */ 249 250 #if !defined (CY_CRYPTOLITE_H) 251 #define CY_CRYPTOLITE_H 252 253 #include "cy_device.h" 254 255 #if defined (CY_IP_MXCRYPTOLITE) 256 257 #include "cy_cryptolite_sha256.h" 258 #include "cy_cryptolite_hmac.h" 259 #include "cy_cryptolite_ecdsa.h" 260 #include "cy_cryptolite_rsa.h" 261 #include "cy_cryptolite_trng.h" 262 #include "cy_cryptolite_aes.h" 263 264 265 #endif /* CY_IP_MXCRYPTOLITE */ 266 267 #endif /* #if !defined (CY_CRYPTOLITE_H) */ 268 /** \} group_cryptolite */ 269 270 /* [] END OF FILE */ 271
