esp-idf/components/hal/include/hal/ecc_hal.h
2023-03-13 16:39:46 +05:30

201 lines
5.9 KiB
C

/*
* SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
/*******************************************************************************
* NOTICE
* The HAL is not public api, don't use in application code.
* See readme.md in soc/README.md
******************************************************************************/
#pragma once
#include "stdint.h"
#include <stdbool.h>
#include "soc/soc_caps.h"
#include "hal/ecc_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Set the work mode of the operation
*
* @param mode Mode of operation
*/
void ecc_hal_set_mode(ecc_mode_t mode);
/**
* @brief Set the ECC curve of operation
*
* @param curve Curve to use for operation
*/
void ecc_hal_set_curve(ecc_curve_t curve);
/**
* @brief Start calculation
*
*/
void ecc_hal_start_calc(void);
/**
* @brief Check whether the calculation has finished
*
* @return - 1 if the hardware has finished calculating
* - 0 otherwise
*/
int ecc_hal_is_calc_finished(void);
/**
* @brief Write parameters for point multiplication (K * (Px, Py))
*
* @param k Scalar value
* @param px X coordinate of the ECC point
* @param py Y coordinate of the ECC point
* @param len Length (in bytes) of the ECC point
* - 32 bytes for SECP256R1
* - 24 bytes for SECP192R1
*/
void ecc_hal_write_mul_param(const uint8_t *k, const uint8_t *px, const uint8_t *py, uint16_t len);
/**
* @brief Write parameters for point verification,
* i.e to check if the point lies on the curve
*
* @param px X coordinate of the ECC point
* @param py Y coordinate of the ECC point
* @param len Length (in bytes) of the ECC point
* - 32 for SECP256R1
* - 24 for SECP192R1
*/
void ecc_hal_write_verify_param(const uint8_t *px, const uint8_t *py, uint16_t len);
/**
* @brief Read point multiplication result
*
* @param rx X coordinate of the multiplication result
* @param ry Y coordinate of the multiplication result
* @param len Length (in bytes) of the ECC point
* - 32 for SECP256R1
* - 24 for SECP192R1
*
* @return - 0 if the operation was successful
* - -1 if the operation was not successful
*
* In case the operation is not successful, rx and ry will contain
* all zeros
*/
int ecc_hal_read_mul_result(uint8_t *rx, uint8_t *ry, uint16_t len);
/**
* @brief Read point verification result
*
* @return - 1 if point lies on curve
* - 0 otherwise
*/
int ecc_hal_read_verify_result(void);
#if SOC_ECC_EXTENDED_MODES_SUPPORTED
/**
* @brief Set the mod base value used in MOD operation
*
* @param base Identifier of the base to use
*/
void ecc_hal_set_mod_base(ecc_mod_base_t base);
/**
* @brief Write parameters for Jacobian verification
* i.e Check whether (Qx, Qy, Qz) is a point on selected curve
*
* @param qx X coordinate of the ECC point in jacobian form
* @param qy Y coordinate of the ECC point in jacobian form
* @param qz Z coordinate of the ECC point in jacobian form
* @param len Length (in bytes) of the ECC point
* - 32 bytes for SECP256R1
* - 24 bytes for SECP192R1
*/
void ecc_hal_write_jacob_verify_param(const uint8_t *qx, const uint8_t *qy, const uint8_t *qz, uint16_t len);
/**
* @brief Read ECC point multiplication result in jacobian form
*
* @param rx X coordinate of the multiplication result
* @param ry Y coordinate of the multiplication result
* @param rz Z coordinate of the multiplication result
* @param len Length (in bytes) of the ECC point
* - 32 for SECP256R1
* - 24 for SECP192R1
*
* @return - 0 if the operation was successful
* - -1 if the operation was not successful
*
* In case the operation is not successful, rx, ry, and rz will contain
* all zeros
*/
int ecc_hal_read_jacob_mul_result(uint8_t *rx, uint8_t *ry, uint8_t *rz, uint16_t len);
/**
* @brief Write parameters for ECC point addition ((Px, Py, 1) + (Qx, Qy, Qz))
*
* @param px X coordinate of the 1st addend ECC point
* @param py Y coordinate of the 1st addend ECC point
* @param qx X coordinate of the 2nd addend ECC point in jacobian form
* @param qy Y coordinate of the 2nd addend ECC point in jacobian form
* @param qz Z coordinate of the 2nd addend ECC point in jacobian form
* @param len Length (in bytes) of the ECC point
* - 32 bytes for SECP256R1
* - 24 bytes for SECP192R1
*/
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);
/**
* @brief Read ECC point addition result
*
* @param rx X coordinate of the addition result
* @param ry Y coordinate of the addition result
* @param rz Z coordinate of the addition result
* @param len Length (in bytes) of the ECC point
* - 32 for SECP256R1
* - 24 for SECP192R1
* @param read_jacob Read the result in Jacobian form
*
* @return - 0 if the operation was successful
* - -1 otherwise
*/
int ecc_hal_read_point_add_result(uint8_t *rx, uint8_t *ry, uint8_t *rz, uint16_t len, bool read_jacob);
/**
* @brief Write parameters for mod operations
* i.e mod add, mod sub, mod mul, mod inverse mul (or mod division)
*
* @param a Value of operand 1
* @param b Value of operand 2
* @param len Length (in bytes) of the ECC point
* - 32 bytes for SECP256R1
* - 24 bytes for SECP192R1
*/
void ecc_hal_write_mod_op_param(const uint8_t *a, const uint8_t *b, uint16_t len);
/**
* @brief Read result of mod operations
* i.e mod add, mod sub, mod mul, mod inverse mul (or mod division)
*
* @param r Result of the mod operation
* @param len Length (in bytes) of the ECC point
* - 32 bytes for SECP256R1
* - 24 bytes for SECP192R1
*
* @return - 0 if operation successful
* - -1 otherwise
*/
int ecc_hal_read_mod_op_result(uint8_t *r, uint16_t len);
#endif /* SOC_ECC_EXTENDED_MODES_SUPPORTED */
#ifdef __cplusplus
}
#endif