Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
crypto_ecc_hw.h
1 /*
2  * Copyright (c) 2022, Nuvoton Technology Corporation
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 #ifndef CRYPTO_ECC_HW_H
20 #define CRYPTO_ECC_HW_H
21 
22 #if !defined(MBEDTLS_CONFIG_FILE)
23 #include "mbedtls/config.h"
24 #else
25 #include MBEDTLS_CONFIG_FILE
26 #endif
27 
28 #if defined(MBEDTLS_ECP_ALT) || defined(MBEDTLS_ECP_INTERNAL_ALT)
29 
30 #include "mbedtls/ecp.h"
31 #include <stdbool.h>
32 
33 /* Crypto ECC H/W point operations */
34 #define ECCOP_POINT_MUL (0x0UL << CRPT_ECC_CTL_ECCOP_Pos)
35 #define ECCOP_MODULE (0x1UL << CRPT_ECC_CTL_ECCOP_Pos)
36 #define ECCOP_POINT_ADD (0x2UL << CRPT_ECC_CTL_ECCOP_Pos)
37 #define ECCOP_POINT_DOUBLE (0x3UL << CRPT_ECC_CTL_ECCOP_Pos)
38 
39 /* Crypto ECC H/W modulus operations */
40 #define MODOP_DIV (0x0UL << CRPT_ECC_CTL_MODOP_Pos)
41 #define MODOP_MUL (0x1UL << CRPT_ECC_CTL_MODOP_Pos)
42 #define MODOP_ADD (0x2UL << CRPT_ECC_CTL_MODOP_Pos)
43 #define MODOP_SUB (0x3UL << CRPT_ECC_CTL_MODOP_Pos)
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 
49 /**
50  * \brief This function checks whether a given group can be used
51  * for Crypto ECC H/W.
52  *
53  * \param grp ECP group
54  *
55  * \return \c 1 if the group can be used, \c 0 otherwise
56  */
57 int crypto_ecc_capable(const mbedtls_ecp_group *grp);
58 
59 /**
60  * \brief Initialize/Free Crypto ECC H/W
61  *
62  * \return \c 0 on success.
63  * \return A non-zero error code on failure.
64  *
65  * \note crypto_ecp_init()/crypto_ecp_free() are like pre-op/post-op calls
66  * and they guarantee:
67  *
68  * 1. Paired
69  * 2. No overlapping
70  * 3. Upper public function cannot return when ECP alter. is still activated.
71  */
72 int crypto_ecc_init(const mbedtls_ecp_group *grp);
73 void crypto_ecc_free(const mbedtls_ecp_group *grp);
74 /**
75  * \brief Configure ECCOP operation, start it, and wait for its completion
76  *
77  * \param grp ECP group
78  * \param R Destination point
79  * \param m Integer by which to multiply P
80  * \param P Point to multiply by m
81  * \param n Integer by which to multiply Q
82  * \param Q Point to be multiplied by n
83  * \param eccop ECCOP code. Could be ECCOP_POINT_MUL/ADD/DOUBLE
84  * \param blinding Blinding (SCAP) or not.
85  * Dependent on passed-in eccop, only partial parameters among m/P/n/Q are needed and checked.
86  * ECCOP_POINT_MUL R = m*P
87  * ECCOP_POINT_ADD R = P + Q
88  * ECCOP_POINT_DOUBLE R = 2*P
89  *
90  * \return 0 if successful
91  *
92  * \note P/Q must be normalized (= affine). R would be normalized.
93  *
94  * \note m/n could be negative.
95  *
96  * \note ECC accelerator doesn't support R = 0, and we need to detect it additionally.
97  * For R = P + Q or R = 2*P, we can detect all R = 0 cases.
98  * For R = m*P, we can detect all R = 0 cases only if grp->N (order) is a prime.
99  *
100  * \note According to ECCOP operation, n is unnecessary. But to be consistent with R = m*P + n*Q,
101  * n is kept with unused modifier.
102  *
103  * \note Blinding (SCAP) is applicable only for point multiplication. But for future extension,
104  * blinding is kept with all point operations.
105  *
106  */
107 int crypto_ecc_run_eccop_add(const mbedtls_ecp_group *grp,
108  mbedtls_ecp_point *R,
109  const mbedtls_ecp_point *P,
110  const mbedtls_ecp_point *Q,
111  bool blinding);
112 int crypto_ecc_run_eccop_double(const mbedtls_ecp_group *grp,
113  mbedtls_ecp_point *R,
114  const mbedtls_ecp_point *P,
115  bool blinding);
116 int crypto_ecc_run_eccop_mul(const mbedtls_ecp_group *grp,
117  mbedtls_ecp_point *R,
118  const mbedtls_mpi *m,
119  const mbedtls_ecp_point *P,
120  bool blinding);
121 int crypto_ecc_run_eccop(const mbedtls_ecp_group *grp,
122  mbedtls_ecp_point *R,
123  const mbedtls_mpi *m,
124  const mbedtls_ecp_point *P,
125  const mbedtls_mpi *n,
126  const mbedtls_ecp_point *Q,
127  uint32_t eccop,
128  bool blinding);
129 
130 /**
131  * \brief Configure MODOP operation and wait for its completion
132  *
133  * \param r Destination MPI
134  * \param o1 Input MPI for first operand of MODOP
135  * \param o2 Input MPI for second operand of MODOP
136  * \param p Prime modulus
137  * \param pbits Bit number of p
138  * \param modop ECCOP code. Could be MODOP_ADD/SUB/MUL/DIV
139  * MODOP_ADD r = o1 + o2 mod p
140  * MODOP_SUB r = o1 - o2 mod p
141  * MODOP_MUL r = o1 * o2 mod p
142  * MODOP_DIV r = o1 / o2 mod p
143  *
144  * \return 0 if successful
145  *
146  * \note o1/o2 must be normalized (within [0, p - 1]). r would be normalized.
147  */
148 int crypto_ecc_run_modop(mbedtls_mpi *r,
149  const mbedtls_mpi *o1,
150  const mbedtls_mpi *o2,
151  const mbedtls_mpi *p,
152  uint32_t pbits,
153  uint32_t modop);
154 
155 /**
156  * \brief Import X from ECC registers, little endian
157  *
158  * \param X Destination MPI
159  * \param eccreg Start of input ECC register
160  * \param eccreg_num Number of input ECC register
161  *
162  * \return 0 if successful
163  *
164  * \note Destination MPI is always non-negative.
165  */
166 int crypto_ecc_mpi_read_eccreg( mbedtls_mpi *X, const volatile uint32_t *eccreg, size_t eccreg_num );
167 
168 /**
169  * \brief Export X into ECC registers, little endian
170  *
171  * \param X Source MPI
172  * \param eccreg Start of ECC output registers
173  * \param eccreg_num Number of ECC output registers
174  *
175  * \return 0 if successful
176  *
177  * \note Source MPI cannot be negative.
178  * \note Fills the remaining MSB ECC registers with zeros if X doesn't cover all.
179  */
180 int crypto_ecc_mpi_write_eccreg( const mbedtls_mpi *X, volatile uint32_t *eccreg, size_t eccreg_num );
181 
182 /**
183  * \brief Abort Crypto ECC H/W
184  *
185  * \param timeout_us Timeout in microseconds.
186  *
187  * \return \c 0 on success.
188  * \return A non-zero error code on failure.
189  */
190 int crypto_ecc_abort(uint32_t timeout_us);
191 
192 #ifdef __cplusplus
193 }
194 #endif
195 
196 #endif /* MBEDTLS_ECP_ALT || MBEDTLS_ECP_INTERNAL_ALT */
197 #endif /* CRYPTO_ECC_HW_H */
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.