Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
crys_ec_mont_api.h
Go to the documentation of this file.
1 /**************************************************************************************
2 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved *
3 * *
4 * This file and the related binary are licensed under the following license: *
5 * *
6 * ARM Object Code and Header Files License, v1.0 Redistribution. *
7 * *
8 * Redistribution and use of object code, header files, and documentation, without *
9 * modification, are permitted provided that the following conditions are met: *
10 * *
11 * 1) Redistributions must reproduce the above copyright notice and the *
12 * following disclaimer in the documentation and/or other materials *
13 * provided with the distribution. *
14 * *
15 * 2) Unless to the extent explicitly permitted by law, no reverse *
16 * engineering, decompilation, or disassembly of is permitted. *
17 * *
18 * 3) Redistribution and use is permitted solely for the purpose of *
19 * developing or executing applications that are targeted for use *
20 * on an ARM-based product. *
21 * *
22 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
23 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT *
24 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, *
25 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE *
26 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED *
28 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR *
29 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF *
30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING *
31 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS *
32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
33 **************************************************************************************/
34 
35 
36 
37 #ifndef CRYS_ECMONT_API_H
38 #define CRYS_ECMONT_API_H
39 
40 #include "ssi_pal_types.h"
41 #include "crys_rnd.h"
42 #include "crys_pka_defs_hw.h"
43 
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47 
48 /*!
49 @file
50 @brief This file contains the CRYS APIs used for EC MONT (Montgomery Curve25519) algorithms.
51 @defgroup crys_ec_mont CryptoCell EC Montgomery APIs
52 @{
53 @ingroup cryptocell_ec
54 
55 
56 \note Implemented algorithms according to Montgomery elliptic curves cryptography,
57  developed by Daniel J.Bernstein etc.
58 */
59 
60 /*! EC Montgomery curve25519 modulus size in bits, words and bytes */
61 /*! EC Montgomery modulus size in bits. */
62 #define CRYS_ECMONT_MOD_SIZE_IN_BITS 255U
63 /*! EC Montgomery modulus size in words. */
64 #define CRYS_ECMONT_MOD_SIZE_IN_32BIT_WORDS ((CRYS_ECMONT_MOD_SIZE_IN_BITS + SASI_BITS_IN_32BIT_WORD - 1) / SASI_BITS_IN_32BIT_WORD)
65 /*! EC Montgomery modulus size in bytes. */
66 #define CRYS_ECMONT_MOD_SIZE_IN_BYTES ((CRYS_ECMONT_MOD_SIZE_IN_BITS + SASI_BITS_IN_32BIT_WORD - 1) / sizeof(uint32_t))
67 
68 /*! Constant sizes of special EC_MONT buffers and arrays */
69 /*! EC Montgomery scalar size in bytes. */
70 #define CRYS_ECMONT_SCALARBYTES (CRYS_ECMONT_MOD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
71 /*! EC Montgomery scalar multiplication size in bytes. */
72 #define CRYS_ECMONT_SCALARMULTBYTES (CRYS_ECMONT_MOD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
73 /*! EC Montgomery scalar seed size in bytes. */
74 #define CRYS_ECMONT_SEEDBYTES (CRYS_ECMONT_MOD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
75 
76 /*! EC Montgomery domains ID-s enumerator. */
77 typedef enum {
78  CRYS_ECMONT_DOMAIN_CURVE_25519, /*!< EC Curve25519. */
79  /*! EC Montgomery last domain. */
80  CRYS_ECMONT_DOMAIN_OFF_MODE,
81  /*! Reserved. */
82  CRYS_ECMONT_DOMAIN_LAST = 0x7FFFFFFF
83 }CRYS_ECMONT_DomainId_t;
84 
85 
86 /*! EC_MONT scalar mult temp buffer type definition */
87 typedef struct {
88  /*! Internal temporary buffer. */
89  uint32_t ecMontScalarMultTempBuff[CRYS_EC_MONT_TEMP_BUFF_SIZE_IN_32BIT_WORDS]; // set needed
90 } CRYS_ECMONT_ScalrMultTempBuff_t;
91 
92 /*! EC_MONT temp buffer type definition */
93 typedef struct {
94  /* Don't change sequence order of the buffers */
95  /*! Internal temporary buffer. */
96  uint32_t ecMontScalar[CRYS_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS];
97  /*! Internal temporary buffer. */
98  uint32_t ecMontResPoint[CRYS_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS];
99  /*! Internal temporary buffer. */
100  uint32_t ecMontInPoint[CRYS_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS];
101  /*! Internal temporary buffer. */
102  CRYS_ECMONT_ScalrMultTempBuff_t ecMontScalrMultTempBuff; // if needed
103 } CRYS_ECMONT_TempBuff_t;
104 
105 
106 /*********************************************************************/
107 /*!
108 @brief The function performs EC Montgomery (Curve25519) scalar multiplication:
109  resPoint = scalar * point.
110 
111 @return CRYS_OK on success,
112 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h.
113 */
114 CIMPORT_C CRYSError_t CRYS_ECMONT_Scalarmult(
115  uint8_t *pResPoint, /*!< [out] Pointer to the public (secret) key. */
116  size_t *pResPointSize, /*!< [in/out] Pointer to the size of the public key in bytes.
117  In - the size of the buffer. must be at least EC modulus
118  size (for curve25519 - 32 bytes).
119  Out - the actual size. */
120  const uint8_t *pScalar, /*!< [in] Pointer to the secret (private) key. */
121  size_t scalarSize, /*!< [in] Pointer to the size of the secret key in bytes;
122  must be equal to EC order size (for curve25519 - 32 bytes). */
123  const uint8_t *pInPoint, /*!< [in] Pointer to the input point (compressed). */
124  size_t inPointSize, /*!< [in] Size of the point - must be equal to CRYS_ECMONT_MOD_SIZE_IN_BYTES. */
125  CRYS_ECMONT_TempBuff_t *pEcMontTempBuff /*!< [in] Pointer to temp buffer, for internal use. */);
126 
127 
128 /*********************************************************************/
129 /*!
130 @brief The function performs EC Montgomery (Curve25519) scalar multiplication of base point:
131  res = scalar * base_point.
132 
133  Note: all byte arrays have LE order of bytes, i.e. LS byte is on left most place.
134 
135 @return CRYS_OK on success,
136 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h.
137 */
138 CIMPORT_C CRYSError_t CRYS_ECMONT_ScalarmultBase(
139  uint8_t *pResPoint, /*!< [out] Pointer to the public (secret) key. */
140  size_t *pResPointSize, /*!< [in/out] Pointer to the size of the public key in bytes.
141  In - the size of buffer must be at least EC modulus size
142  (for curve25519 - 32 bytes);
143  Out - the actual size. */
144  const uint8_t *pScalar, /*!< [in] Pointer to the secret (private) key. */
145  size_t scalarSize, /*!< [in] Pointer to the size of the scalar in bytes -
146  must be equal to EC order size (for curve25519 - 32 bytes). */
147  CRYS_ECMONT_TempBuff_t *pEcMontTempBuff /*!< [in] Pointer to temp buffer, for internal use. */);
148 
149 
150 /*******************************************************************/
151 /*!
152 @brief The function randomly generates private and public keys for Montgomery
153  Curve25519.
154 
155 
156 \note <ul id="noteb"><li> All byte arrays are in LE order of bytes, i.e. LS byte is on the left most place.</li>
157  <li> LS and MS bits of the Secret key are set according to EC Montgomery scalar mult. algorithm:
158  secrKey[0] &= 248; secrKey[31] &= 127; secrKey[31] |= 64;</li></ul>
159 
160 @return CRYS_OK on success,
161 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_rnd_error.h.
162 
163 */
164 CIMPORT_C CRYSError_t CRYS_ECMONT_KeyPair (
165  uint8_t *pPublKey, /*!< [out] Pointer to the public key. */
166  size_t *pPublKeySize, /*!< [in/out] Pointer to the size of the public key in bytes.
167  In - the size of the buffer must be at least EC order size
168  (for curve25519 - 32 bytes);
169  Out - the actual size. */
170  uint8_t *pSecrKey, /*!< [out] Pointer to the secret key, including. */
171  size_t *pSecrKeySize, /*!< [in/out] Pointer to the size of buffer for the secret key in bytes -
172  must be at least EC order size (for curve25519 - 32 bytes). */
173  void *pRndState, /*!< [in/out] Pointer to the RND state structure. */
174  SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, /*!< [in] Pointer to the random vector generation function. */
175  CRYS_ECMONT_TempBuff_t *pEcMontTempBuff /*!< [in] Pointer to the temp buffer, for internal use. */);
176 
177 
178 /*******************************************************************/
179 /*!
180 @brief The function generates private and public keys for Montgomery algorithms.
181 
182  The generation performed using given seed.
183 
184 
185 @return CRYS_OK on success,
186 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_hash_error.h.
187 */
188 CIMPORT_C CRYSError_t CRYS_ECMONT_SeedKeyPair (
189  uint8_t *pPublKey, /*!< [out] Pointer to the public (secret) key. */
190  size_t *pPublKeySize, /*!< [in/out] Pointer to the size of the public key in bytes.
191  In - the size of buffer must be at least EC order size
192  (for curve25519 - 32 bytes);
193  Out - the actual size. */
194  uint8_t *pSecrKey, /*!< [out] Pointer to the secret (private) key. */
195  size_t *pSecrKeySize, /*!< [in/out] Pointer to the size of the secret key in bytes
196  In - the size of buffer must be at least EC order size
197  (for curve25519 - 32 bytes);
198  Out - the actual size. */
199  const uint8_t *pSeed, /*!< [in] Pointer to the given seed - 32 bytes. */
200  size_t seedSize, /*!< [in/] Size of the seed in bytes (must be equal to CRYS_ECMONT_SEEDBYTES). */
201  CRYS_ECMONT_TempBuff_t *pEcMontTempBuff /*!< [in] Pointer to a temp buffer, for internal use. */);
202 
203 
204 #ifdef __cplusplus
205 }
206 #endif
207 /**
208 @}
209  */
210 #endif
211 
212 
213 
CRYS_ECMONT_DOMAIN_CURVE_25519
Definition: crys_ec_mont_api.h:78
CRYS_ECMONT_DOMAIN_LAST
Definition: crys_ec_mont_api.h:82
CRYS_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS
#define CRYS_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS
Definition: crys_pka_defs_hw.h:115
CRYS_ECMONT_DomainId_t
CRYS_ECMONT_DomainId_t
Definition: crys_ec_mont_api.h:77
CRYS_ECMONT_Scalarmult
CRYSError_t CRYS_ECMONT_Scalarmult(uint8_t *pResPoint, size_t *pResPointSize, const uint8_t *pScalar, size_t scalarSize, const uint8_t *pInPoint, size_t inPointSize, CRYS_ECMONT_TempBuff_t *pEcMontTempBuff)
The function performs EC Montgomery (Curve25519) scalar multiplication: resPoint = scalar * point...
CRYS_ECMONT_TempBuff_t::ecMontScalrMultTempBuff
CRYS_ECMONT_ScalrMultTempBuff_t ecMontScalrMultTempBuff
Definition: crys_ec_mont_api.h:102
CRYS_ECMONT_ScalarmultBase
CRYSError_t CRYS_ECMONT_ScalarmultBase(uint8_t *pResPoint, size_t *pResPointSize, const uint8_t *pScalar, size_t scalarSize, CRYS_ECMONT_TempBuff_t *pEcMontTempBuff)
The function performs EC Montgomery (Curve25519) scalar multiplication of base point: res = scalar * ...
crys_pka_defs_hw.h
The file contains all of the enums and definitions that are used in the PKA related code...
CRYS_ECMONT_TempBuff_t
Definition: crys_ec_mont_api.h:93
CRYS_ECMONT_ScalrMultTempBuff_t
Definition: crys_ec_mont_api.h:87
CRYS_ECMONT_DOMAIN_OFF_MODE
Definition: crys_ec_mont_api.h:80
CRYS_ECMONT_KeyPair
CRYSError_t CRYS_ECMONT_KeyPair(uint8_t *pPublKey, size_t *pPublKeySize, uint8_t *pSecrKey, size_t *pSecrKeySize, void *pRndState, SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, CRYS_ECMONT_TempBuff_t *pEcMontTempBuff)
The function randomly generates private and public keys for Montgomery Curve25519.
crys_rnd.h
This file contains the CRYS APIs used for random number generation. The random-number generation modu...
CRYSError_t
uint32_t CRYSError_t
Definition: crys_error.h:253
ssi_pal_types.h
This file contains the platform dependent definitions and types.
SaSiRndGenerateVectWorkFunc_t
uint32_t(* SaSiRndGenerateVectWorkFunc_t)(void *rndState_ptr, uint16_t outSizeBytes, uint8_t *out_ptr)
Definition: crys_rnd.h:206
CRYS_EC_MONT_TEMP_BUFF_SIZE_IN_32BIT_WORDS
#define CRYS_EC_MONT_TEMP_BUFF_SIZE_IN_32BIT_WORDS
Definition: crys_pka_defs_hw.h:117
CRYS_ECMONT_SeedKeyPair
CRYSError_t CRYS_ECMONT_SeedKeyPair(uint8_t *pPublKey, size_t *pPublKeySize, uint8_t *pSecrKey, size_t *pSecrKeySize, const uint8_t *pSeed, size_t seedSize, CRYS_ECMONT_TempBuff_t *pEcMontTempBuff)
The function generates private and public keys for Montgomery algorithms.
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.