1 /* 2 * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /******************************************************************************* 8 * NOTICE 9 * The HAL is not public api, don't use in application code. 10 * See readme.md in soc/README.md 11 ******************************************************************************/ 12 13 #pragma once 14 15 #include "stdint.h" 16 #include <stdbool.h> 17 #include "soc/soc_caps.h" 18 #include "hal/ecc_types.h" 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /** 25 * @brief Set the work mode of the operation 26 * 27 * @param mode Mode of operation 28 */ 29 void ecc_hal_set_mode(ecc_mode_t mode); 30 31 /** 32 * @brief Set the ECC curve of operation 33 * 34 * @param curve Curve to use for operation 35 */ 36 void ecc_hal_set_curve(ecc_curve_t curve); 37 38 /** 39 * @brief Start calculation 40 * 41 */ 42 void ecc_hal_start_calc(void); 43 44 /** 45 * @brief Check whether the calculation has finished 46 * 47 * @return - 1 if the hardware has finished calculating 48 * - 0 otherwise 49 */ 50 int ecc_hal_is_calc_finished(void); 51 52 /** 53 * @brief Write parameters for point multiplication (K * (Px, Py)) 54 * 55 * @param k Scalar value 56 * @param px X coordinate of the ECC point 57 * @param py Y coordinate of the ECC point 58 * @param len Length (in bytes) of the ECC point 59 * - 32 bytes for SECP256R1 60 * - 24 bytes for SECP192R1 61 */ 62 void ecc_hal_write_mul_param(const uint8_t *k, const uint8_t *px, const uint8_t *py, uint16_t len); 63 64 /** 65 * @brief Write parameters for point verification, 66 * i.e to check if the point lies on the curve 67 * 68 * @param px X coordinate of the ECC point 69 * @param py Y coordinate of the ECC point 70 * @param len Length (in bytes) of the ECC point 71 * - 32 for SECP256R1 72 * - 24 for SECP192R1 73 */ 74 void ecc_hal_write_verify_param(const uint8_t *px, const uint8_t *py, uint16_t len); 75 76 /** 77 * @brief Read point multiplication result 78 * 79 * @param rx X coordinate of the multiplication result 80 * @param ry Y coordinate of the multiplication result 81 * @param len Length (in bytes) of the ECC point 82 * - 32 for SECP256R1 83 * - 24 for SECP192R1 84 * 85 * @return - 0 if the operation was successful 86 * - -1 if the operation was not successful 87 * 88 * In case the operation is not successful, rx and ry will contain 89 * all zeros 90 */ 91 int ecc_hal_read_mul_result(uint8_t *rx, uint8_t *ry, uint16_t len); 92 93 /** 94 * @brief Read point verification result 95 * 96 * @return - 1 if point lies on curve 97 * - 0 otherwise 98 */ 99 int ecc_hal_read_verify_result(void); 100 101 #if SOC_ECC_EXTENDED_MODES_SUPPORTED 102 /** 103 * @brief Set the mod base value used in MOD operation 104 * 105 * @param base Identifier of the base to use 106 */ 107 void ecc_hal_set_mod_base(ecc_mod_base_t base); 108 109 /** 110 * @brief Write parameters for Jacobian verification 111 * i.e Check whether (Qx, Qy, Qz) is a point on selected curve 112 * 113 * @param qx X coordinate of the ECC point in jacobian form 114 * @param qy Y coordinate of the ECC point in jacobian form 115 * @param qz Z coordinate of the ECC point in jacobian form 116 * @param len Length (in bytes) of the ECC point 117 * - 32 bytes for SECP256R1 118 * - 24 bytes for SECP192R1 119 */ 120 void ecc_hal_write_jacob_verify_param(const uint8_t *qx, const uint8_t *qy, const uint8_t *qz, uint16_t len); 121 122 /** 123 * @brief Read ECC point multiplication result in jacobian form 124 * 125 * @param rx X coordinate of the multiplication result 126 * @param ry Y coordinate of the multiplication result 127 * @param rz Z coordinate of the multiplication result 128 * @param len Length (in bytes) of the ECC point 129 * - 32 for SECP256R1 130 * - 24 for SECP192R1 131 * 132 * @return - 0 if the operation was successful 133 * - -1 if the operation was not successful 134 * 135 * In case the operation is not successful, rx, ry, and rz will contain 136 * all zeros 137 */ 138 int ecc_hal_read_jacob_mul_result(uint8_t *rx, uint8_t *ry, uint8_t *rz, uint16_t len); 139 140 /** 141 * @brief Write parameters for ECC point addition ((Px, Py, 1) + (Qx, Qy, Qz)) 142 * 143 * @param px X coordinate of the 1st addend ECC point 144 * @param py Y coordinate of the 1st addend ECC point 145 * @param qx X coordinate of the 2nd addend ECC point in jacobian form 146 * @param qy Y coordinate of the 2nd addend ECC point in jacobian form 147 * @param qz Z coordinate of the 2nd addend ECC point in jacobian form 148 * @param len Length (in bytes) of the ECC point 149 * - 32 bytes for SECP256R1 150 * - 24 bytes for SECP192R1 151 */ 152 void ecc_hal_write_point_add_param(const uint8_t *px, const uint8_t *py, const uint8_t *qx, const uint8_t *qy, const uint8_t *qz, uint16_t len); 153 154 /** 155 * @brief Read ECC point addition result 156 * 157 * @param rx X coordinate of the addition result 158 * @param ry Y coordinate of the addition result 159 * @param rz Z coordinate of the addition result 160 * @param len Length (in bytes) of the ECC point 161 * - 32 for SECP256R1 162 * - 24 for SECP192R1 163 * @param read_jacob Read the result in Jacobian form 164 * 165 * @return - 0 if the operation was successful 166 * - -1 otherwise 167 */ 168 int ecc_hal_read_point_add_result(uint8_t *rx, uint8_t *ry, uint8_t *rz, uint16_t len, bool read_jacob); 169 170 /** 171 * @brief Write parameters for mod operations 172 * i.e mod add, mod sub, mod mul, mod inverse mul (or mod division) 173 * 174 * @param a Value of operand 1 175 * @param b Value of operand 2 176 * @param len Length (in bytes) of the ECC point 177 * - 32 bytes for SECP256R1 178 * - 24 bytes for SECP192R1 179 */ 180 void ecc_hal_write_mod_op_param(const uint8_t *a, const uint8_t *b, uint16_t len); 181 182 /** 183 * @brief Read result of mod operations 184 * i.e mod add, mod sub, mod mul, mod inverse mul (or mod division) 185 * 186 * @param r Result of the mod operation 187 * @param len Length (in bytes) of the ECC point 188 * - 32 bytes for SECP256R1 189 * - 24 bytes for SECP192R1 190 * 191 * @return - 0 if operation successful 192 * - -1 otherwise 193 */ 194 int ecc_hal_read_mod_op_result(uint8_t *r, uint16_t len); 195 196 #endif /* SOC_ECC_EXTENDED_MODES_SUPPORTED */ 197 198 #ifdef __cplusplus 199 } 200 #endif 201
