1 /******************************************************************************
2 *  Filename:       rom_crypto.h
3 *
4 *  Description:    This header file is the API to the crypto functions
5 *                  built into ROM on the CC13xx/CC26xx.
6 *
7 *  Copyright (c) 2015 - 2022, Texas Instruments Incorporated
8 *  All rights reserved.
9 *
10 *  Redistribution and use in source and binary forms, with or without
11 *  modification, are permitted provided that the following conditions are met:
12 *
13 *  1) Redistributions of source code must retain the above copyright notice,
14 *     this list of conditions and the following disclaimer.
15 *
16 *  2) Redistributions in binary form must reproduce the above copyright notice,
17 *     this list of conditions and the following disclaimer in the documentation
18 *     and/or other materials provided with the distribution.
19 *
20 *  3) Neither the name of the ORGANIZATION nor the names of its contributors may
21 *     be used to endorse or promote products derived from this software without
22 *     specific prior written permission.
23 *
24 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
28 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 *  POSSIBILITY OF SUCH DAMAGE.
35 *
36 *******************************************************************************/
37 
38 //*****************************************************************************
39 //
40 //! \addtogroup peripheral_group
41 //! @{
42 //! \addtogroup rom_crypto_api
43 //! @{
44 //
45 //*****************************************************************************
46 
47 #ifndef ROM_CRYPTO_H
48 #define ROM_CRYPTO_H
49 
50 #ifdef __cplusplus
51 extern "C"
52 {
53 #endif
54 
55 ////////////////////////////////////* ECC */////////////////////////////////////
56 
57 /* Curve Parameters in ROM */
58 
59 /* Curve parameters for the NISTP256 curve. These curve parameters are stored
60  * in ROM and can be accessed via the pointers below.
61  * Each curve parameter starts with the 32-bit word 0x08 followed by the actual
62  * parameter encoded in 32 bytes as a little-endian integer.
63  */
64 #define ECC_NISTP256_prime ((const uint32_t *) 0x100257d4)
65 #define ECC_NISTP256_order ((const uint32_t *) 0x100257f8)
66 #define ECC_NISTP256_a ((const uint32_t *) 0x1002581c)
67 #define ECC_NISTP256_b ((const uint32_t *) 0x10025840)
68 #define ECC_NISTP256_generatorX ((const uint32_t *) 0x10025864)
69 #define ECC_NISTP256_generatorY ((const uint32_t *) 0x10025888)
70 
71 /* Length in bytes of NISTP256 curve parameters excluding the prepended length
72  * word.
73  */
74 #define ECC_NISTP256_PARAM_LENGTH_BYTES 32
75 
76 /* Length in words of NISTP256 curve parameters excluding the prepended length
77  * word.
78  */
79 #define ECC_NISTP256_PARAM_LENGTH_WORDS (ECC_NISTP256_PARAM_LENGTH_BYTES / sizeof(uint32_t))
80 
81 /* Number of bytes for the length word prepended before all parameters passed
82  * into the ECC functions.
83  */
84 #define ECC_LENGTH_OFFSET_BYTES 4
85 
86 /* Window size, valid values are 2,3,4,5.
87  * Higher the value, faster the computation at the expense of memory usage.
88  *
89  * Recommended workzone size (in 4-byte words)
90  * Window size: 3, Workzone size: 275
91  *
92  */
93 #define ECC_WINDOW_SIZE 3
94 
95 /*
96  * ECC Supported Curves, define one:
97  * ECC_PRIME_NIST256_CURVE
98  */
99 #define ECC_PRIME_NIST256_CURVE
100 
101 /*
102  * ECC Return Status Flags.
103  */
104 // Scalar multiplication status
105 #define ECC_MODULUS_EVEN                   0xDC
106 #define ECC_MODULUS_LARGER_THAN_255_WORDS  0xD2
107 #define ECC_MODULUS_LENGTH_ZERO            0x08
108 #define ECC_MODULUS_MSW_IS_ZERO            0x30
109 #define ECC_SCALAR_TOO_LONG                0x35
110 #define ECC_SCALAR_LENGTH_ZERO             0x53
111 #define ECC_ORDER_TOO_LONG                 0xC6
112 #define ECC_ORDER_LENGTH_ZERO              0x6C
113 #define ECC_X_COORD_TOO_LONG               0x3C
114 #define ECC_X_COORD_LENGTH_ZERO            0xC3
115 #define ECC_Y_COORD_TOO_LONG               0x65
116 #define ECC_Y_COORD_LENGTH_ZERO            0x56
117 #define ECC_A_COEF_TOO_LONG                0x5C
118 #define ECC_A_COEF_LENGTH_ZERO             0xC5
119 #define ECC_BAD_WINDOW_SIZE                0x66
120 #define ECC_SCALAR_MUL_OK                  0x99
121 
122 // ECDSA and ECDH status
123 #define ECC_ORDER_LARGER_THAN_255_WORDS    0x28
124 #define ECC_ORDER_EVEN                     0x82
125 #define ECC_ORDER_MSW_IS_ZERO              0x23
126 #define ECC_ECC_KEY_TOO_LONG               0x25
127 #define ECC_ECC_KEY_LENGTH_ZERO            0x52
128 #define ECC_DIGEST_TOO_LONG                0x27
129 #define ECC_DIGEST_LENGTH_ZERO             0x72
130 #define ECC_ECDSA_SIGN_OK                  0x32
131 #define ECC_ECDSA_INVALID_SIGNATURE        0x5A
132 #define ECC_ECDSA_VALID_SIGNATURE          0xA5
133 #define ECC_SIG_P1_TOO_LONG                0x11
134 #define ECC_SIG_P1_LENGTH_ZERO             0x12
135 #define ECC_SIG_P2_TOO_LONG                0x22
136 #define ECC_SIG_P2_LENGTH_ZERO             0x21
137 
138 #define ECC_ECDSA_KEYGEN_OK                ECC_SCALAR_MUL_OK
139 #define ECC_ECDH_KEYGEN_OK                 ECC_SCALAR_MUL_OK
140 #define ECC_ECDH_COMMON_KEY_OK             ECC_SCALAR_MUL_OK
141 
142 //*****************************************************************************
143 /*!
144  * \brief Initialize elliptic curve parameters to default values and specify workzone.
145  *
146  * This function initializes the elliptic curve parameters to default values.
147  * The default elliptic curve used is NIST-P256.
148  *
149  * The workzone defaults to an expected window size of 3.
150  *
151  * This function can be called again to point the ECC workzone at
152  * a different memory buffer.
153  *
154  * \param pWorkzone Pointer to memory allocated for computations, input.
155  *                  See description at beginning of ECC section for
156  *                  memory requirements.
157  *
158  * \return None
159  */
160 //*****************************************************************************
161 extern void ECC_initialize(uint32_t *pWorkzone);
162 
163 //*****************************************************************************
164 /*!
165  *  \brief Initialize elliptic curve parameters to specified values and specify workzone.
166  *
167  *  This function may be used to explicitly specify the curve parameters used
168  *  by the ECC in ROM implementation.
169  *
170  *  All curve parameters must be prepended with a length word specifying the
171  *  length of the parameter in 32-bit words excluding the length word itself.
172  *  For NIST-P256, the length word is 8.
173  *
174  *  @param workzone   Pointer to memory allocated for computations, input.
175  *                    See description at beginning of ECC section for
176  *                    memory requirements.
177  *  @param windowSize Window size of \c workzone. Default value is 3.
178  *  @param prime      Curve prime
179  *  @param order      Curve order
180  *  @param a          Curve a value
181  *  @param b          Curve b value
182  *  @param generatorX X coordinate of generator point
183  *  @param generatorY Y coordinate of generator point
184  */
185 extern void ECC_init(uint32_t *workzone,
186                      uint8_t   windowSize,
187                      const uint32_t *prime,
188                      const uint32_t *order,
189                      const uint32_t *a,
190                      const uint32_t *b,
191                      const uint32_t *generatorX,
192                      const uint32_t *generatorY);
193 
194 //*****************************************************************************
195  /*!
196  * \brief Generate a key.
197  *
198  * This is used for both ECDH and ECDSA.
199  *
200  * \param randString  Pointer to random string, input.
201  * \param privateKey  Pointer to the private key, output.
202  * \param publicKey_x Pointer to public key X-coordinate, output.
203  * \param publicKey_y Pointer to public key Y-coordinate, output.
204  *
205  * \return Status
206  */
207 //*****************************************************************************
208 extern uint8_t ECC_generateKey(uint32_t *randString, uint32_t *privateKey,
209                                uint32_t *publicKey_x, uint32_t *publicKey_y);
210 
211 //*****************************************************************************
212 /*!
213  * \brief Sign data.
214  *
215  * \param secretKey  Pointer to the secret key, input.
216  * \param text       Pointer to the message, input.
217  * \param randString Pointer to random string, input.
218  * \param sign1      Pointer to signature part 1, output.
219  * \param sign2      Pointer to signature part 2, output.
220  *
221  * \return Status
222  */
223 //*****************************************************************************
224 extern uint8_t ECC_ECDSA_sign(uint32_t *secretKey, uint32_t *text, uint32_t *randString,
225                               uint32_t *sign1, uint32_t *sign2);
226 
227 //*****************************************************************************
228 /*!
229  * \brief Verify signature.
230  *
231  * \param publicKey_x Pointer to public key X-coordinate, input.
232  * \param publicKey_y Pointer to public key Y-coordinate, input.
233  * \param text        Pointer to message data, input.
234  * \param sign1       Pointer to signature part 1, input.
235  * \param sign2       Pointer to signature part 2, input.
236  *
237  * \return Status
238  */
239 //*****************************************************************************
240 extern uint8_t ECC_ECDSA_verify(uint32_t *publicKey_x, uint32_t *publicKey_y,
241                                 uint32_t *text, uint32_t *sign1, uint32_t *sign2);
242 
243 //*****************************************************************************
244 /*!
245  * \brief Compute the shared secret.
246  *
247  * \param privateKey     Pointer to private key, input.
248  * \param publicKey_x    Pointer to public key X-coordinate, input.
249  * \param publicKey_y    Pointer to public key Y-coordinate, input.
250  * \param sharedSecret_x Pointer to shared secret X-coordinate, output.
251  * \param sharedSecret_y Pointer to shared secret Y-coordinate, output.
252  *
253  * \return Status
254  */
255 //*****************************************************************************
256 extern uint8_t ECC_ECDH_computeSharedSecret(uint32_t *privateKey,
257                                             uint32_t *publicKey_x,
258                                             uint32_t *publicKey_y,
259                                             uint32_t *sharedSecret_x,
260                                             uint32_t *sharedSecret_y);
261 
262 #ifdef __cplusplus
263 }
264 #endif
265 
266 #endif /* ROM_CRYPTO_H */
267 
268 //*****************************************************************************
269 //
270 //! Close the Doxygen group.
271 //! @}
272 //! @}
273 //
274 //*****************************************************************************
275