1 /***************************************************************************//** 2 * \file cy_cryptolite_rsa.h 3 * \version 2.50 4 * 5 * \brief 6 * This file provides provides constant and parameters 7 * for the API of the RSA in the Cryptolite driver. 8 * 9 ******************************************************************************** 10 * Copyright 2020-2021 Cypress Semiconductor Corporation 11 * SPDX-License-Identifier: Apache-2.0 12 * 13 * Licensed under the Apache License, Version 2.0 (the "License"); 14 * you may not use this file except in compliance with the License. 15 * You may obtain a copy of the License at 16 * 17 * http://www.apache.org/licenses/LICENSE-2.0 18 * 19 * Unless required by applicable law or agreed to in writing, software 20 * distributed under the License is distributed on an "AS IS" BASIS, 21 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 22 * See the License for the specific language governing permissions and 23 * limitations under the License. 24 *******************************************************************************/ 25 26 #if !defined (CY_CRYPTOLITE_RSA_H) 27 #define CY_CRYPTOLITE_RSA_H 28 29 #include "cy_device.h" 30 31 #if defined (CY_IP_MXCRYPTOLITE) 32 33 #if defined(__cplusplus) 34 extern "C" { 35 #endif 36 37 #include "cy_cryptolite_common.h" 38 #include "cy_cryptolite_vu.h" 39 40 #if (CRYPTOLITE_VU_PRESENT == 1) 41 #if defined(CY_CRYPTOLITE_CFG_RSA_C) 42 43 /* Max key size to support must be defined */ 44 #if defined (CY_CRYPTOLITE_CFG_RSA_MAX_KEY_512) 45 #define CY_CRYPTOLITE_RSA_BITSIZE (512U) 46 #elif defined (CY_CRYPTOLITE_CFG_RSA_MAX_KEY_1024) 47 #define CY_CRYPTOLITE_RSA_BITSIZE (1024U) 48 #elif defined (CY_CRYPTOLITE_CFG_RSA_MAX_KEY_2048) 49 #define CY_CRYPTOLITE_RSA_BITSIZE (2048U) 50 #elif defined(CY_CRYPTOLITE_CFG_RSA_MAX_KEY_3072) 51 #define CY_CRYPTOLITE_RSA_BITSIZE (3072U) 52 #elif defined(CY_CRYPTOLITE_CFG_RSA_MAX_KEY_4096) 53 #define CY_CRYPTOLITE_RSA_BITSIZE (4096U) 54 #else 55 #define CY_CRYPTOLITE_RSA_BITSIZE (4096U) 56 #endif 57 58 59 /* The buffer size needed by the IP for the internal RSA calculation*/ 60 #define CY_CRYPTOLITE_RSA_BUFFER_SIZE (4U*VU_BITS_TO_WORDS(2U*CY_CRYPTOLITE_RSA_BITSIZE+1U) \ 61 + 4U*VU_BITS_TO_WORDS(2U*CY_CRYPTOLITE_RSA_BITSIZE+1U)\ 62 + 4U*VU_BITS_TO_WORDS(CY_CRYPTOLITE_RSA_BITSIZE) + 4U*VU_BITS_TO_WORDS(CY_CRYPTOLITE_RSA_BITSIZE)) 63 64 65 /** 66 * \addtogroup group_cryptolite_data_structures 67 * \{ 68 */ 69 70 /** 71 * All fields for the context structure are internal. Firmware never reads or 72 * writes these values. Firmware allocates the structure and provides the 73 * address of the structure to the driver in the function calls. Firmware must 74 * ensure that the defined instance of this structure remains in scope 75 * while the drive is in use. 76 * 77 * The driver uses this structure to store and manipulate the RSA public key and 78 * additional coefficients to accelerate RSA calculation. 79 * 80 * RSA key contained from two fields: 81 * - n - modulus part of the key 82 * - e - exponent part of the key. 83 * 84 * Other fields are accelerating coefficients and can be calculated by 85 * Cy_Cryptolite_Rsa_Coef API. 86 * 87 * \note All the buffers must be 4 byte aligned in the 88 * \ref cy_stc_cryptolite_rsa_pub_key_t and must also be in little-endian order.<br> 89 * Use Cy_Cryptolite_InvertEndianness function to convert to or from 90 * little-endian order. 91 */ 92 CY_ALIGN(4) 93 typedef struct 94 { 95 /** The pointer to the modulus part of public key. */ 96 uint8_t *moduloPtr; 97 /** The modulus length, in bits, maximum supported size is 4096 Bits */ 98 uint32_t moduloLength; 99 100 /** The pointer to the exponent part of public key */ 101 uint8_t *pubExpPtr; 102 /** The exponent length, in bits, maximum supported size is 256Bit */ 103 uint32_t pubExpLength; 104 105 /** The pointer to the Barrett coefficient. Memory for it should be 106 allocated by user with size moduloLength + 1. */ 107 uint8_t *barretCoefPtr; 108 109 /** The pointer to the binary inverse of the modulo. Memory for it 110 should be allocated by user with size moduloLength. */ 111 uint8_t *inverseModuloPtr; 112 113 /** The pointer to the (2^moduloLength mod modulo). Memory for it should 114 be allocated by user with size moduloLength */ 115 uint8_t *rBarPtr; 116 117 /** when set to 'true', pre-calculated coefficients must be provided in 'barretCoefPtr, 'inverseModuloPtr' and 'rBarPtr', 118 can be calculated by Cy_Cryptolite_Rsa_Coef API . 119 When set to 'false', all the acceleration step coefficients will be calculated as part of \ref Cy_Cryptolite_Rsa_Proc */ 120 bool preCalculatedCoeff; 121 122 } cy_stc_cryptolite_rsa_pub_key_t; 123 124 /*All buffers must be 4 byte aligned*/ 125 typedef struct cy_stc_cryptolite_rsa_buffer_t 126 { 127 /** \cond INTERNAL */ 128 CY_ALIGN(4) uint8_t p_buffer[CY_CRYPTOLITE_RSA_BUFFER_SIZE]; 129 /*Assigned dummy byte for the 4 byte alignment*/ 130 CY_ALIGN(4) uint32_t dummy[1u]; 131 /** \endcond */ 132 }cy_stc_cryptolite_rsa_buffer_t; 133 134 typedef struct cy_stc_cryptolite_context_rsa_t 135 { 136 /** \cond INTERNAL */ 137 uint8_t *p_buffer; 138 /* two vector unit structures, each structure is 16 bytes*/ 139 cy_stc_cryptolite_descr_t vu_desptr[2]; 140 /** \endcond */ 141 }cy_stc_cryptolite_context_rsa_t; 142 143 /** \} group_cryptolite_data_structures */ 144 145 146 /** 147 * \addtogroup group_cryptolite_lld_asymmetric_functions 148 * \{ 149 */ 150 151 /******************************************************************************* 152 * Function Name: Cy_Cryptolite_Rsa_Init 153 ****************************************************************************//** 154 * 155 * Initialize the RSA context. 156 * 157 * \param base 158 * The pointer to the CRYPTOLITE instance. 159 * 160 * \param cfContext 161 * The pointer to the CRYPTOLITE context. 162 * 163 * \param rsaBuffers 164 * The pointer to the RSA buffers. 165 * 166 * \return 167 * \ref cy_en_cryptolite_status_t 168 * 169 * \funcusage 170 * \snippet cryptolite/snippet/main.c snippet_rsa_signature_verify 171 *******************************************************************************/ 172 cy_en_cryptolite_status_t Cy_Cryptolite_Rsa_Init(CRYPTOLITE_Type *base, 173 cy_stc_cryptolite_context_rsa_t *cfContext, 174 cy_stc_cryptolite_rsa_buffer_t *rsaBuffers); 175 176 177 178 /******************************************************************************* 179 * Function Name: Cy_Cryptolite_Core_Rsa_Proc 180 ****************************************************************************//** 181 * 182 * RSA process algorithm based on the Montgomery algorithm 183 * using Barrett reduction 184 * 185 * https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29 186 * 187 * Key, message, processedMessage buffers must be 4 byte aligned and end with 4 byte boundary. 188 * 189 * \param base 190 * The pointer to the CRYPTOLITE instance. 191 * 192 * \param cfContext 193 * The pointer to the CRYPTOLITE context. 194 * 195 * \param key 196 * The pointer to the \ref cy_stc_cryptolite_rsa_pub_key_t structure that stores 197 * public key. 198 * 199 * \param message 200 * The pointer to the message to be processed. 201 * 202 * \param messageSize 203 * The length of the message to be processed. 204 * 205 * \param processedMessage 206 * The pointer to processed message. 207 * 208 * \return 209 * \ref cy_en_cryptolite_status_t 210 * 211 * \funcusage 212 * \snippet cryptolite/snippet/main.c snippet_rsa_signature_verify 213 *******************************************************************************/ 214 cy_en_cryptolite_status_t Cy_Cryptolite_Rsa_Proc(CRYPTOLITE_Type *base, 215 cy_stc_cryptolite_context_rsa_t *cfContext, 216 cy_stc_cryptolite_rsa_pub_key_t *key, 217 uint8_t const *message, 218 uint32_t messageSize, 219 uint8_t *processedMessage); 220 221 222 /******************************************************************************* 223 * Function Name: Cy_Cryptolite_Rsa_Coef 224 ****************************************************************************//** 225 * 226 * Calculation constant coefficients to speed-up Montgomery algorithm. 227 * These coefficients are: 228 * coefficient for Barrett reduction, 229 * binary inverse of the modulo, 230 * result of (2^moduloLength mod modulo) 231 * 232 * \param base 233 * The pointer to the CRYPTOLITE instance. 234 * 235 * \param cfContext 236 * The pointer to the CRYPTOLITE context. 237 * 238 * \param key 239 * The pointer to the \ref cy_stc_cryptolite_rsa_pub_key_t structure that stores a 240 * public key. 241 * 242 * \return 243 * \ref cy_en_cryptolite_status_t 244 * 245 *******************************************************************************/ 246 cy_en_cryptolite_status_t Cy_Cryptolite_Rsa_Coef(CRYPTOLITE_Type *base, 247 cy_stc_cryptolite_context_rsa_t *cfContext, 248 cy_stc_cryptolite_rsa_pub_key_t *key); 249 250 251 252 /******************************************************************************* 253 * Function Name: Cy_Cryptolite_Rsa_Free 254 ****************************************************************************//** 255 * 256 * Cleanup the RSA context. 257 * 258 * \param base 259 * The pointer to the CRYPTOLITE instance. 260 * 261 * \param cfContext 262 * The pointer to the CRYPTOLITE context. 263 * 264 * \return 265 * \ref cy_en_cryptolite_status_t 266 * 267 * \funcusage 268 * \snippet cryptolite/snippet/main.c snippet_rsa_signature_verify 269 *******************************************************************************/ 270 cy_en_cryptolite_status_t Cy_Cryptolite_Rsa_Free(CRYPTOLITE_Type *base, 271 cy_stc_cryptolite_context_rsa_t *cfContext); 272 273 #ifdef CY_CRYPTOLITE_CFG_RSA_VERIFY_ENABLED 274 275 /******************************************************************************* 276 * Function Name: Cy_Cryptolite_Rsa_Verify 277 ****************************************************************************//** 278 * 279 * RSA verification with checks for content, paddings and signature format. 280 * SHA digest of the message and decrypted message should be calculated before. 281 * Supports only PKCS1-v1_5 format, inside of this format supported padding 282 * using only SHA, cases with MD2 and MD5 are not supported. 283 * PKCS1-v1_5 described here, page 31: 284 * http://www.emc.com/collateral/white-papers/h11300-pkcs-1v2-2-rsa-cryptography-standard-wp.pdf 285 * 286 * The digest and decryptedSignature buffers must be 4 byte aligned 287 * 288 * Returns the verification result \ref cy_en_cryptolite_sig_verify_result_t. 289 * 290 * \param base 291 * The pointer to the CRYPTOLITE instance. 292 * 293 * \param cfContext 294 * The pointer to the CRYPTOLITE context. 295 * 296 * \param verResult 297 * The pointer to the verification result \ref cy_en_cryptolite_sig_verify_result_t. 298 * 299 * \param digestType 300 * SHA mode used for hash calculation \ref cy_en_cryptolite_sha_mode_t. 301 * 302 * \param digest 303 * The pointer to the hash of the message or the message whose signature is to be verified. 304 * 305 * \param digestLength 306 * The length of the message whose signature is to be verified and is applicable for CY_CRYPTOLITE_MODE_SHA_NONE mode. 307 * 308 * \param decryptedSignature 309 * The pointer to the decrypted signature to be verified. 310 * 311 * \param decryptedSignatureLength 312 * The length of the decrypted signature to be verified (in bytes) 313 * 314 * \return 315 * \ref cy_en_cryptolite_status_t 316 * 317 * \funcusage 318 * \snippet cryptolite/snippet/main.c snippet_rsa_signature_verify 319 *******************************************************************************/ 320 cy_en_cryptolite_status_t Cy_Cryptolite_Rsa_Verify(CRYPTOLITE_Type *base, 321 cy_stc_cryptolite_context_rsa_t *cfContext, 322 cy_en_cryptolite_sig_verify_result_t *verResult, 323 cy_en_cryptolite_sha_mode_t digestType, 324 uint8_t const *digest, 325 uint32_t digestLength, 326 uint8_t const *decryptedSignature, 327 uint32_t decryptedSignatureLength); 328 #endif 329 330 /** \} group_cryptolite_lld_asymmetric_functions */ 331 332 #endif /*#if (CY_CRYPTOLITE_CFG_RSA_C)*/ 333 #endif /* #if (CPUSS_CRYPTOLITE_VU == 1) */ 334 335 #if defined(__cplusplus) 336 } 337 #endif 338 339 #endif /* CY_IP_MXCRYPTOLITE */ 340 341 #endif /* #if !defined (CY_CRYPTOLITE_RSA_H) */ 342 343 /* [] END OF FILE */ 344
