1 /*
2  * Copyright (c) 2024, The TrustedFirmware-M Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 
8 #ifndef __CC3XX_EC_PROJECTIVE_POINT_H__
9 #define __CC3XX_EC_PROJECTIVE_POINT_H__
10 
11 #include <stdint.h>
12 #include <stddef.h>
13 
14 #include "cc3xx_ec.h"
15 
16 typedef struct {
17     cc3xx_pka_reg_id_t x;
18     cc3xx_pka_reg_id_t y;
19     cc3xx_pka_reg_id_t z;
20 } cc3xx_ec_point_projective;
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25 
26 /**
27  * @brief                        Allocate a projective EC point.
28  *
29  * @return                       An initialized projective EC point.
30  */
31 cc3xx_ec_point_projective cc3xx_lowlevel_ec_allocate_projective_point(void);
32 
33 /**
34  * @brief                        Free a projective EC point.
35  *
36  * @param[in]  p                 A pointer to the projective point to free.
37  */
38 void cc3xx_lowlevel_ec_free_projective_point(cc3xx_ec_point_projective *p);
39 
40 /**
41  * @brief                        Copy a projective EC point.
42  *
43  * @param[in]  p                 A pointer to the projective point to copy.
44  * @param[out] res               A pointer to the projective point to copy into.
45  */
46 void cc3xx_lowlevel_ec_copy_projective_point(cc3xx_ec_point_projective *p,
47                                              cc3xx_ec_point_projective *res);
48 
49 /**
50  * @brief                        Test if a projective point is infinity.
51  *
52  * @param[in]  p                 A pointer to the projective point to test.
53  *
54  * @return                       true if the projective point is the infinity
55  *                               point, false if it isn't.
56  */
57 bool cc3xx_lowlevel_ec_projective_point_is_infinity(cc3xx_ec_point_projective *p);
58 
59 /**
60  * @brief                        Convert an affine point to a Jacobian-form
61  *                               projective point. Xa = Xj / Zj^2,
62  *                               Ya = Yj / Zj^2. Should not be used on secret
63  *                               data.
64  *
65  * @param[in]  curve             A pointer to an initialized curve object
66  * @param[in]  p                 A pointer to the projective point to copy.
67  * @param[out] res               A pointer to the projective point to copy into.
68  */
69 void cc3xx_lowlevel_ec_affine_to_jacobian(cc3xx_ec_curve_t *curve,
70                                           cc3xx_ec_point_affine *p,
71                                           cc3xx_ec_point_projective *res);
72 
73 /**
74  * @brief                        Convert an affine point to a Jacobian-form
75  *                               projective point, with a random Z coordinate.
76  *                               Xa = Xj / Zj^2, Ya = Yj / Zj^2.
77  *
78  * @note                         If DPA mitigations are disabled by config, this
79  *                               function falls back to having a Z coordinate of
80  *                               1.
81  *
82  * @param[in]  curve             A pointer to an initialized curve object
83  * @param[in]  p                 A pointer to the affine point to convert.
84  * @param[out] res               A pointer to the Jacobian point object.
85  */
86 void cc3xx_lowlevel_ec_affine_to_jacobian_with_random_z(cc3xx_ec_curve_t *curve,
87                                                         cc3xx_ec_point_affine *p,
88                                                         cc3xx_ec_point_projective *res);
89 
90 /**
91  * @brief                        Convert a Jacobian-form projective point to an
92  *                               Affine point.
93  *                               Xa = Xj / Zj^2, Ya = Yj / Zj^2.
94  *
95  * @param[in]  curve             A pointer to an initialized curve object
96  * @param[in]  p                 A pointer to the Jacobian point to convert.
97  * @param[out] res               A pointer to the affine point object.
98  */
99 cc3xx_err_t cc3xx_lowlevel_ec_jacobian_to_affine(cc3xx_ec_curve_t *curve,
100                                                  cc3xx_ec_point_projective *p,
101                                                  cc3xx_ec_point_affine *res);
102 
103 #ifdef __cplusplus
104 }
105 #endif
106 
107 #endif /* __CC3XX_EC_PROJECTIVE_POINT_H__ */
108