1 /* 2 * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #pragma once 7 8 #include_next "mbedtls/bignum.h" 9 #include "sdkconfig.h" 10 11 /** 12 * This is a wrapper for the main mbedtls/bignum.h. This wrapper 13 * provides a few additional ESP32-only functions. 14 * 15 * This is because we don't set MBEDTLS_BIGNUM_ALT in the same way we 16 * do for AES, SHA, etc. Because we still use most of the bignum.h 17 * implementation and just replace a few hardware accelerated 18 * functions (see MBEDTLS_MPI_EXP_MOD_ALT & MBEDTLS_MPI_MUL_MPI_ALT in 19 * esp_config.h). 20 * 21 * @note Unlike the other hardware accelerator support functions in esp32/hwcrypto, there is no 22 * generic "hwcrypto/bignum.h" header for using these functions without mbedTLS. The reason for this 23 * is that all of the function implementations depend strongly upon the mbedTLS MPI implementation. 24 */ 25 26 /** 27 * @brief Lock access to RSA Accelerator (MPI/bignum operations) 28 * 29 * RSA Accelerator hardware unit can only be used by one 30 * consumer at a time. 31 * 32 * @note This function is non-recursive (do not call it twice from the 33 * same task.) 34 * 35 * @note You do not need to call this if you are using the mbedTLS bignum.h 36 * API or esp_mpi_xxx functions. This function is only needed if you 37 * want to call ROM RSA functions or access the registers directly. 38 * 39 */ 40 void esp_mpi_acquire_hardware(void); 41 42 /** 43 * @brief Unlock access to RSA Accelerator (MPI/bignum operations) 44 * 45 * Has to be called once for each call to esp_mpi_acquire_hardware(). 46 * 47 * @note You do not need to call this if you are using the mbedTLS bignum.h 48 * API or esp_mpi_xxx functions. This function is only needed if you 49 * want to call ROM RSA functions or access the registers directly. 50 */ 51 void esp_mpi_release_hardware(void); 52 53 #if CONFIG_MBEDTLS_HARDWARE_MPI 54 55 /* @brief MPI modular mupltiplication function 56 * 57 * Calculates Z = (X * Y) mod M using MPI hardware acceleration. 58 * 59 * This is not part of the standard mbedTLS bignum API. 60 * 61 * @note All of X, Y & Z should be less than 4096 bit long or an error is returned. 62 * 63 * @param Z Result bignum, should be pre-initialised with mbedtls_mpi_init(). 64 * @param X First multiplication argument. 65 * @param Y Second multiplication argument. 66 * @param M Modulus value for result. 67 * 68 * @return 0 on success, mbedTLS MPI error codes on failure. 69 */ 70 int esp_mpi_mul_mpi_mod(mbedtls_mpi *Z, const mbedtls_mpi *X, const mbedtls_mpi *Y, const mbedtls_mpi *M); 71 72 #if CONFIG_MBEDTLS_LARGE_KEY_SOFTWARE_MPI 73 74 /** 75 * @brief Perform a sliding-window exponentiation: X = A^E mod N 76 * 77 * @param X The destination MPI. This must point to an initialized MPI. 78 * @param A The base of the exponentiation. 79 * This must point to an initialized MPI. 80 * @param E The exponent MPI. This must point to an initialized MPI. 81 * @param N The base for the modular reduction. This must point to an 82 * initialized MPI. 83 * @param _RR A helper MPI depending solely on \p N which can be used to 84 * speed-up multiple modular exponentiations for the same value 85 * of \p N. This may be \c NULL. If it is not \c NULL, it must 86 * point to an initialized MPI. 87 * 88 * @return \c 0 if successful. 89 * @return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. 90 * @return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \c N is negative or 91 * even, or if \c E is negative. 92 * @return Another negative error code on different kinds of failures. 93 * 94 */ 95 int mbedtls_mpi_exp_mod_soft(mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *E, const mbedtls_mpi *N, mbedtls_mpi *_RR); 96 97 #endif // CONFIG_MBEDTLS_LARGE_KEY_SOFTWARE_MPI 98 99 #endif // CONFIG_MBEDTLS_HARDWARE_MPI 100
