Contiki-NG
bignum-driver.h
Go to the documentation of this file.
1 /*
2  * Original file:
3  * Copyright (C) 2013 Texas Instruments Incorporated - http://www.ti.com/
4  * All rights reserved.
5  *
6  * Port to Contiki:
7  * Authors: Andreas Dröscher <contiki@anticat.ch>
8  * Hu Luo
9  * Hossein Shafagh <shafagh@inf.ethz.ch>
10  *
11  * Redistribution and use in source and binary forms, with or without
12  * modification, are permitted provided that the following conditions
13  * are met:
14  * 1. Redistributions of source code must retain the above copyright
15  * notice, this list of conditions and the following disclaimer.
16  * 2. Redistributions in binary form must reproduce the above copyright
17  * notice, this list of conditions and the following disclaimer in the
18  * documentation and/or other materials provided with the distribution.
19  *
20  * 3. Neither the name of the copyright holder nor the names of its
21  * contributors may be used to endorse or promote products derived
22  * from this software without specific prior written permission.
23  *
24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
27  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
28  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
29  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
30  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
31  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
33  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
35  * OF THE POSSIBILITY OF SUCH DAMAGE.
36  */
37 /**
38  * \addtogroup cc2538-pka
39  * @{
40  *
41  * \defgroup cc2538-bignum cc2538 BigNum math function driver
42  *
43  * Driver for the cc2538 BigNum math functions of the PKC engine
44  * @{
45  *
46  * \file
47  * Header file for the cc2538 BigNum driver
48  *
49  * bignum_subtract_start bignum_subtract_get_result (subtraction)
50  * bignum_add_start bignum_add_get_result (addition)
51  * bignum_mod_start bignum_mod_get_result (modulo)
52  * bignum_exp_mod_start bignum_exp_mod_get_result (modular exponentiation operation)
53  * bignum_inv_mod_start bignum_inv_mod_get_result (inverse modulo operation)
54  * bignum_mul_start bignum_mul_get_result (multiplication)
55  * bignum_divide_start bignum_divide_get_result (division)
56  * bignum_cmp_start bignum_cmp_get_result (comparison)
57  */
58 #ifndef BIGNUM_DRIVER_H_
59 #define BIGNUM_DRIVER_H_
60 
61 #include "contiki.h"
62 #include "dev/pka.h"
63 
64 #include <stdint.h>
65 
66 /** @} */
67 /*---------------------------------------------------------------------------*/
68 /** \brief Starts the big number modulus operation.
69  *
70  * \param number Pointer to the big number on which modulo operation
71  * needs to be carried out.
72  * \param number_size Size of the big number \sa number in 32-bit word.
73  * \param modulus Pointer to the divisor.
74  * \param modulus_size Size of the divisor \sa modulus.
75  * \param result_vector Pointer to the result vector location
76  * which will be set by this function.
77  * \param process Process to be polled upon completion of the
78  * operation, or \c NULL
79  *
80  * This function starts the modulo operation on the big num \sa number
81  * using the divisor \sa modulus. The PKA RAM location where the result
82  * will be available is stored in \sa result_vector.
83  *
84  * \retval PKA_STATUS_SUCCESS if successful in starting the operation.
85  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
86  * some other operation.
87  */
88 uint8_t bignum_mod_start(const uint32_t *number,
89  const uint8_t number_size,
90  const uint32_t *modulus,
91  const uint8_t modulus_size,
92  uint32_t *result_vector,
93  struct process *process);
94 
95 /** \brief Gets the result of the big number modulus operation.
96  *
97  * \param buffer Pointer to buffer where the result needs to
98  * be stored.
99  * \param buffer_size Size of the provided buffer in 32 bit size word.
100  * \param result_vector Address of the result location which
101  * was provided by the start function \sa PKABigNumModStart().
102  *
103  * This function gets the result of the big number modulus operation which was
104  * previously started using the function \sa PKABigNumModStart().
105  *
106  * \retval PKA_STATUS_SUCCESS if successful.
107  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
108  * the operation.
109  * \retval PKA_STATUS_RESULT_0 if the result is all zeroes.
110  * \retval PKA_STATUS_BUF_UNDERFLOW if the \e size is less than the length
111  * of the result.
112  */
113 uint8_t bignum_mod_get_result(uint32_t *buffer,
114  const uint8_t buffer_size,
115  const uint32_t result_vector);
116 
117 /** \brief Starts the comparison of two big numbers.
118  *
119  * \param number1 Pointer to the first big number.
120  * \param number2 Pointer to the second big number.
121  * \param size Size of the big number in 32 bit size word.
122  * \param process Process to be polled upon completion of the
123  * operation, or \c NULL
124  *
125  * This function starts the comparison of two big numbers pointed by
126  * \e number1 and \e number2.
127  * Note this function expects the size of the two big numbers equal.
128  *
129  * \retval PKA_STATUS_SUCCESS if successful in starting the operation.
130  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
131  * some other operation.
132  */
133 uint8_t bignum_cmp_start(const uint32_t *number1,
134  const uint32_t *number2,
135  uint8_t size,
136  struct process *process);
137 
138 /** \brief Gets the result of the comparison operation of two big numbers.
139  *
140  * This function provides the results of the comparison of two big numbers
141  * which was started using the \sa PKABigNumCmpStart().
142  *
143  * \retval PKA_STATUS_OPERATION_INPRG if the operation is in progress.
144  * \retval PKA_STATUS_SUCCESS if the two big numbers are equal.
145  * \retval PKA_STATUS_A_GR_B if the first number is greater than the second.
146  * \retval PKA_STATUS_A_LT_B if the first number is less than the second.
147  */
148 uint8_t bignum_cmp_get_result(void);
149 
150 /** \brief Starts the big number inverse modulo operation.
151  *
152  * \param number Pointer to the buffer containing the big number
153  * (dividend).
154  * \param number_size Size of the \e number in 32 bit word.
155  * \param modulus Pointer to the buffer containing the modulus.
156  * \param modulus_size Size of the modulus in 32 bit word.
157  * \param result_vector Pointer to the result vector location
158  * which will be set by this function.
159  * \param process Process to be polled upon completion of the
160  * operation, or \c NULL
161  *
162  * This function starts the the inverse modulo operation on \e number
163  * using the divisor \e modulus.
164  *
165  * \retval PKA_STATUS_SUCCESS if successful in starting the operation.
166  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
167  * some other operation.
168  */
169 uint8_t bignum_inv_mod_start(const uint32_t *number,
170  const uint8_t number_size,
171  const uint32_t *modulus,
172  const uint8_t modulus_size,
173  uint32_t *result_vector,
174  struct process *process);
175 
176 /** \brief Gets the result of the big number inverse modulo operation.
177  *
178  * \param buffer Pointer to buffer where the result needs to be
179  * stored.
180  * \param buffer_size Size of the provided buffer in 32 bit size
181  * word.
182  * \param result_vector Address of the result location which
183  * was provided by the start function \sa PKABigNumInvModStart().
184  *
185  * This function gets the result of the big number inverse modulo operation
186  * previously started using the function \sa PKABigNumInvModStart().
187  *
188  * \retval PKA_STATUS_SUCCESS if the operation is successful.
189  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy performing
190  * the operation.
191  * \retval PKA_STATUS_RESULT_0 if the result is all zeroes.
192  * \retval PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less
193  * then the result.
194  */
195 uint8_t bignum_inv_mod_get_result(uint32_t *buffer,
196  const uint8_t buffer_size,
197  const uint32_t result_vector);
198 
199 /** \brief Starts the big number multiplication.
200  *
201  * \param multiplicand Pointer to the buffer containing the big
202  * number multiplicand.
203  * \param multiplicand_size Size of the multiplicand in 32-bit word.
204  * \param multiplier Pointer to the buffer containing the big
205  * number multiplier.
206  * \param multiplier_size Size of the multiplier in 32-bit word.
207  * \param result_vector Pointer to the result vector location
208  * which will be set by this function.
209  * \param process Process to be polled upon completion of the
210  * operation, or \c NULL
211  *
212  * This function starts the multiplication of the two big numbers.
213  *
214  * \retval PKA_STATUS_SUCCESS if successful in starting the operation.
215  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
216  * some other operation.
217  */
218 uint8_t bignum_mul_start(const uint32_t *multiplicand,
219  const uint8_t multiplicand_size,
220  const uint32_t *multiplier,
221  const uint8_t multiplier_size,
222  uint32_t *result_vector,
223  struct process *process);
224 
225 /** \brief Gets the results of the big number multiplication.
226  *
227  * \param buffer Pointer to buffer where the result needs to be stored.
228  * \param buffer_size Address of the variable containing the length of the
229  * buffer. After the operation, the actual length of the resultant is
230  * stored at this address.
231  * \param result_vector Address of the result location which
232  * was provided by the start function \sa PKABigNumMultiplyStart().
233  *
234  * This function gets the result of the multiplication of two big numbers
235  * operation previously started using the function \sa
236  * PKABigNumMultiplyStart().
237  *
238  * \retval PKA_STATUS_SUCCESS if the operation is successful.
239  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy performing
240  * the operation.
241  * \retval PKA_STATUS_RESULT_0 if the result is all zeroes.
242  * \retval PKA_STATUS_FAILURE if the operation is not successful.
243  * \retval PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less
244  * then the length of the result.
245  */
246 uint8_t bignum_mul_get_result(uint32_t *buffer,
247  uint32_t *buffer_size,
248  const uint32_t result_vector);
249 
250 /** \brief Starts the addition of two big number.
251  *
252  * \param number1 Pointer to the buffer containing the first big mumber.
253  * \param number1_size Size of the first big number in 32-bit word.
254  * \param number2 Pointer to the buffer containing the second big number.
255  * \param number2_size Size of the second big number in 32-bit word.
256  * \param result_vector Pointer to the result vector location
257  * which will be set by this function.
258  * \param process Process to be polled upon completion of the
259  * operation, or \c NULL
260  *
261  * This function starts the addition of the two big numbers.
262  *
263  * \retval PKA_STATUS_SUCCESS if successful in starting the operation.
264  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
265  * some other operation.
266  */
267 uint8_t bignum_add_start(const uint32_t *number1,
268  const uint8_t number1_size,
269  const uint32_t *number2,
270  const uint8_t number2_size,
271  uint32_t *result_vector,
272  struct process *process);
273 
274 /** \brief Gets the result of the addition operation on two big number.
275  *
276  * \param buffer Pointer to buffer where the result
277  * needs to be stored.
278  * \param buffer_size Address of the variable containing the length of
279  * the buffer. After the operation the actual length of the
280  * resultant is stored at this address.
281  * \param result_vector Address of the result location which
282  * was provided by the start function \sa PKABigNumAddStart().
283  *
284  * This function gets the result of the addition operation on two big numbers,
285  * previously started using the function \sa PKABigNumAddStart().
286  *
287  * \retval PKA_STATUS_SUCCESS if the operation is successful.
288  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy performing
289  * the operation.
290  * \retval PKA_STATUS_RESULT_0 if the result is all zeroes.
291  * \retval PKA_STATUS_FAILURE if the operation is not successful.
292  * \retval PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less
293  * then the length of the result.
294  */
295 uint8_t bignum_add_get_result(uint32_t *buffer,
296  uint32_t *buffer_size,
297  const uint32_t result_vector);
298 
299 /** \brief Starts the substract of two big number.
300  *
301  * \param number1 Pointer to the buffer containing the first big mumber.
302  * \param number1_size Size of the first big number in 32-bit word.
303  * \param number2 Pointer to the buffer containing the second big number.
304  * \param number2_size Size of the second big number in 32-bit word.
305  * \param result_vector Pointer to the result vector location
306  * which will be set by this function.
307  * \param process Process to be polled upon completion of the
308  * operation, or \c NULL
309  *
310  * This function starts the substraction of the two big numbers.
311  *
312  * \retval PKA_STATUS_SUCCESS if successful in starting the operation.
313  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
314  * some other operation.
315  */
316 uint8_t bignum_subtract_start(const uint32_t *number1,
317  const uint8_t number1_size,
318  const uint32_t *number2,
319  const uint8_t number2_size,
320  uint32_t *result_vector,
321  struct process *process);
322 
323 /** \brief Gets the result of big number subtract.
324  *
325  * \param buffer Pointer to store the result of subtraction.
326  * \param buffer_size Address of the variable containing the length of the
327  * buffer. After the operation, the actual length of the resultant is
328  * stored at this address.
329  * \param result_vector Address of the result location which
330  * was provided by the start function PKABigNumSubtractStart().
331  *
332  * This function gets the result of PKABigNumSubtractStart().
333  *
334  * \retval PKA_STATUS_SUCCESS if the operation is successful.
335  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy performing
336  * the operation.
337  * \retval PKA_STATUS_RESULT_0 if the result is all zeroes.
338  * \retval PKA_STATUS_FAILURE if the operation is not successful.
339  */
340 uint8_t bignum_subtract_get_result(uint32_t *buffer,
341  uint32_t *buffer_size,
342  const uint32_t result_vector);
343 
344 /** \brief Starts the big number moduluar Exponentiation operation.
345  *
346  * \param number Pointer to the Exponent on which moduluar Exponentiation operation
347  * needs to be carried out.
348  * \param number_size Size of the the Exponent number number in 32-bit word.
349  * \param modulus Pointer to the divisor.
350  * \param modulus_size Size of the divisor modulus.
351  * \param base Pointer to the Base.
352  * \param base_size Size of the divisor base.
353  * \param result_vector Pointer to the result vector location
354  * which will be set by this function.
355  * \param process Process to be polled upon completion of the
356  * operation, or \c NULL
357  *
358  * This function starts the moduluar Exponentiation operation on the base num base
359  * using the Exponent number and the Modulus num modulus. The PKA RAM location where the result
360  * will be available is stored in \sa result_vector.
361  * IMPORTANT = Modulus and Based should have buffers of the same length!
362  *
363  * \retval PKA_STATUS_SUCCESS if successful in starting the operation.
364  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
365  * some other operation.
366  */
367 uint8_t bignum_exp_mod_start(const uint32_t *number,
368  const uint8_t number_size,
369  const uint32_t *modulus,
370  const uint8_t modulus_size,
371  const uint32_t *base,
372  const uint8_t base_size,
373  uint32_t *result_vector,
374  struct process *process);
375 
376 /** \brief Gets the result of the big number modulus operation result.
377  *
378  * \param buffer Pointer to buffer where the result needs to
379  * be stored.
380  * \param buffer_size Size of the provided buffer in 32 bit size word.
381  * \param result_vector Address of the result location which
382  * was provided by the start function \sa PKABigNumExpModStart().
383  *
384  * This function gets the result of the big number modulus operation which was
385  * previously started using the function \sa PKABigNumExpModStart().
386  *
387  * \retval PKA_STATUS_SUCCESS if successful.
388  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
389  * the operation.
390  * \retval PKA_STATUS_RESULT_0 if the result is all zeroes.
391  * \retval PKA_STATUS_BUF_UNDERFLOW if the \e size is less than the length
392  * of the result.
393  *
394  * \note
395  * - 0 < number_size <= Max_Len
396  * - 1 < modulus_size <=Max_Len
397  * - modulus must be odd and modulus > 232
398  * - base < modulus
399  */
400 uint8_t bignum_exp_mod_get_result(uint32_t *buffer,
401  const uint8_t buffer_size,
402  const uint32_t result_vector);
403 
404 /** \brief Starts the big number Divide.
405  *
406  * \param dividend Pointer to the buffer containing the big
407  * number dividend.
408  * \param dividend_size Size of the dividend in 32-bit word.
409  * \param divisor Pointer to the buffer containing the big
410  * number divisor.
411  * \param divisor_size Size of the divisor in 32-bit word.
412  * \param result_vector Pointer to the result vector location
413  * which will be set by this function.
414  * \param process Process to be polled upon completion of the
415  * operation, or \c NULL
416  *
417  * This function starts the divide of the two big numbers.
418  *
419  * \retval PKA_STATUS_SUCCESS if successful in starting the operation.
420  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy doing
421  * some other operation.
422  */
423 uint8_t bignum_divide_start(const uint32_t *dividend,
424  const uint8_t dividend_size,
425  const uint32_t *divisor,
426  const uint8_t divisor_size,
427  uint32_t *result_vector,
428  struct process *process);
429 
430 /** \brief Gets the results of the big number Divide.
431  *
432  * \param buffer Pointer to buffer where the result needs to be stored.
433  * \param buffer_size Address of the variable containing the length of the
434  * buffer. After the operation, the actual length of the resultant is
435  * stored at this address.
436  * \param result_vector Address of the result location which
437  * was provided by the start function \sa PKABigNumMultiplyStart().
438  *
439  * This function gets the result of the Divide of two big numbers
440  * operation previously started using the function \sa
441  * PKABigNumDivideStart().
442  *
443  * \retval PKA_STATUS_SUCCESS if the operation is successful.
444  * \retval PKA_STATUS_OPERATION_INPRG if the PKA hw module is busy performing
445  * the operation.
446  * \retval PKA_STATUS_RESULT_0 if the result is all zeroes.
447  * \retval PKA_STATUS_FAILURE if the operation is not successful.
448  * \retval PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less
449  * then the length of the result.
450  */
451 uint8_t bignum_divide_get_result(uint32_t *buffer,
452  uint32_t *buffer_size,
453  const uint32_t result_vector);
454 
455 /** @} */
456 
457 #endif /* BIGNUM_DRIVER_H_ */
458 
459 /**
460  * @}
461  * @}
462  */
uint8_t bignum_cmp_start(const uint32_t *number1, const uint32_t *number2, uint8_t size, struct process *process)
Starts the comparison of two big numbers.
uint8_t bignum_add_get_result(uint32_t *buffer, uint32_t *buffer_size, const uint32_t result_vector)
Gets the result of the addition operation on two big number.
uint8_t bignum_subtract_get_result(uint32_t *buffer, uint32_t *buffer_size, const uint32_t result_vector)
Gets the result of big number subtract.
uint8_t bignum_mod_get_result(uint32_t *buffer, const uint8_t buffer_size, const uint32_t result_vector)
Gets the result of the big number modulus operation.
uint8_t bignum_mod_start(const uint32_t *number, const uint8_t number_size, const uint32_t *modulus, const uint8_t modulus_size, uint32_t *result_vector, struct process *process)
Starts the big number modulus operation.
Definition: bignum-driver.c:64
uint8_t bignum_exp_mod_start(const uint32_t *number, const uint8_t number_size, const uint32_t *modulus, const uint8_t modulus_size, const uint32_t *base, const uint8_t base_size, uint32_t *result_vector, struct process *process)
Starts the big number moduluar Exponentiation operation.
uint8_t bignum_inv_mod_get_result(uint32_t *buffer, const uint8_t buffer_size, const uint32_t result_vector)
Gets the result of the big number inverse modulo operation.
uint8_t bignum_cmp_get_result(void)
Gets the result of the comparison operation of two big numbers.
Header file for the cc2538 PKA engine driver.
uint8_t bignum_exp_mod_get_result(uint32_t *buffer, const uint8_t buffer_size, const uint32_t result_vector)
Gets the result of the big number modulus operation result.
uint8_t bignum_inv_mod_start(const uint32_t *number, const uint8_t number_size, const uint32_t *modulus, const uint8_t modulus_size, uint32_t *result_vector, struct process *process)
Starts the big number inverse modulo operation.
uint8_t bignum_mul_get_result(uint32_t *buffer, uint32_t *buffer_size, const uint32_t result_vector)
Gets the results of the big number multiplication.
uint8_t bignum_mul_start(const uint32_t *multiplicand, const uint8_t multiplicand_size, const uint32_t *multiplier, const uint8_t multiplier_size, uint32_t *result_vector, struct process *process)
Starts the big number multiplication.
uint8_t bignum_add_start(const uint32_t *number1, const uint8_t number1_size, const uint32_t *number2, const uint8_t number2_size, uint32_t *result_vector, struct process *process)
Starts the addition of two big number.
uint8_t bignum_subtract_start(const uint32_t *number1, const uint8_t number1_size, const uint32_t *number2, const uint8_t number2_size, uint32_t *result_vector, struct process *process)
Starts the substract of two big number.
uint8_t bignum_divide_start(const uint32_t *dividend, const uint8_t dividend_size, const uint32_t *divisor, const uint8_t divisor_size, uint32_t *result_vector, struct process *process)
Starts the big number Divide.
uint8_t bignum_divide_get_result(uint32_t *buffer, uint32_t *buffer_size, const uint32_t result_vector)
Gets the results of the big number Divide.