1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 8 #ifndef CC_EC_MONT_API_TW_H 9 #define CC_EC_MONT_API_TW_H 10 11 #include "cc_pal_types.h" 12 #include "cc_rnd_common.h" 13 #include "cc_pka_defs_hw.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /*! 20 @file 21 @brief This file contains the CryptoCell APIs used for EC MONT (Montgomery Curve25519) algorithms. 22 @defgroup cc_ec_mont CryptoCell EC Montgomery APIs 23 @{ 24 @ingroup cryptocell_ec 25 26 27 28 \note Implemented algorithms according to Montgomery elliptic curves cryptography, 29 developed by Daniel J.Bernstein etc. 30 */ 31 32 /*! EC Montgomery curve25519 modulus size in bits, words and bytes */ 33 /*! EC Montgomery modulus size in bits. */ 34 #define CC_EC_MONT_MOD_SIZE_IN_BITS 255U 35 /*! EC Montgomery modulus size in words. */ 36 #define CC_EC_MONT_MOD_SIZE_IN_32BIT_WORDS ((CC_EC_MONT_MOD_SIZE_IN_BITS + CC_BITS_IN_32BIT_WORD - 1) / CC_BITS_IN_32BIT_WORD) 37 /*! EC Montgomery modulus size in bytes. */ 38 #define CC_EC_MONT_MOD_SIZE_IN_BYTES ((CC_EC_MONT_MOD_SIZE_IN_BITS + CC_BITS_IN_BYTE - 1) / CC_BITS_IN_BYTE) 39 40 /*! Constant sizes of special EC_MONT buffers and arrays */ 41 /*! EC Montgomery scalar size in bytes. */ 42 #define CC_EC_MONT_SCALARBYTES (CC_EC_MONT_MOD_SIZE_IN_32BIT_WORDS * CC_32BIT_WORD_SIZE) 43 /*! EC Montgomery scalar multiplication size in bytes. */ 44 #define CC_EC_MONT_SCALARMULTBYTES (CC_EC_MONT_MOD_SIZE_IN_32BIT_WORDS * CC_32BIT_WORD_SIZE) 45 /*! EC Montgomery scalar seed size in bytes. */ 46 #define CC_EC_MONT_SEEDBYTES (CC_EC_MONT_MOD_SIZE_IN_32BIT_WORDS * CC_32BIT_WORD_SIZE) 47 48 /*! EC Montgomery domains ID-s enumerator. */ 49 typedef enum 50 { 51 CC_EC_MONT_DOMAIN_CURVE_25519, /*!< EC Curve25519 */ 52 /*! EC Montgomery last domain. */ 53 CC_EC_MONT_DOMAIN_OFF_MODE, 54 /*! Reserved. */ 55 CC_EC_MONT_DOMAIN_LAST = 0x7FFFFFFF 56 }CCEcMontDomainId_t; 57 58 59 /*! EC_MONT scalar mult temp buffer type definition */ 60 typedef struct { 61 /*! Internal temporary buffer. */ 62 uint32_t ecMontScalarMultTempBuff[CC_EC_MONT_TEMP_BUFF_SIZE_IN_32BIT_WORDS]; //! ! Change as needed 63 } CCEcMontScalrMultTempBuff_t; 64 65 /*! EC_MONT temp buffer type definition */ 66 typedef struct { 67 /* Don't change sequence order of the buffers */ 68 /*! Internal temporary buffer. */ 69 uint32_t ecMontScalar[CC_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS]; 70 /*! Internal temporary buffer. */ 71 uint32_t ecMontResPoint[CC_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS]; 72 /*! Internal temporary buffer. */ 73 uint32_t ecMontInPoint[CC_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS]; 74 /*! Internal temporary buffer. */ 75 CCEcMontScalrMultTempBuff_t ecMontScalrMultTempBuff;// if needed ? 76 } CCEcMontTempBuff_t; 77 78 79 /*********************************************************************/ 80 /*! 81 @brief The function performs EC Montgomery (Curve25519) scalar multiplication: 82 resPoint = scalar * point. 83 84 @return CC_OK on success, 85 @return A non-zero value on failure as defined cc_ec_mont_edw_error.h. 86 */ 87 CIMPORT_C CCError_t CC_EcMontScalarmult( 88 uint8_t *pResPoint, /*!< [out] Pointer to the public (secret) key. */ 89 size_t *pResPointSize, /*!< [in/out] Pointer to the size of the public key in bytes. 90 In - the size of the buffer. must be at least EC modulus 91 size (for curve25519 - 32 bytes). 92 Out - the actual size. */ 93 const uint8_t *pScalar, /*!< [in] Pointer to the secret (private) key. */ 94 size_t scalarSize, /*!< [in] Pointer to the size of the secret key in bytes; 95 must be equal to EC order size (for curve25519 - 32 bytes). */ 96 const uint8_t *pInPoint, /*!< [in] Pointer to the input point (compressed). */ 97 size_t inPointSize, /*!< [in] Size of the point - must be equal to CC_EC_MONT_MOD_SIZE_IN_BYTES. */ 98 CCEcMontTempBuff_t *ecMontTempBuff /*!< [in] Pointer to temp buffer, for internal use. */); 99 100 101 102 /*********************************************************************/ 103 /*! 104 @brief The function performs EC Montgomery (Curve25519) scalar multiplication of base point: 105 res = scalar * base_point. 106 107 Note: all byte arrays have LE order of bytes, i.e. LS byte is on left most place. 108 109 @return CC_OK on success, 110 @return A non-zero value on failure as defined cc_ec_mont_edw_error.h. 111 */ 112 CIMPORT_C CCError_t CC_EcMontScalarmultBase( 113 uint8_t *pResPoint, /*!< [out] Pointer to the public (secret) key. */ 114 size_t *pResPointSize, /*!< [in/out] Pointer to the size of the public key in bytes. 115 In - the size of buffer must be at least EC modulus size 116 (for curve25519 - 32 bytes); 117 Out - the actual size. */ 118 const uint8_t *pScalar, /*!< [in] Pointer to the secret (private) key. */ 119 size_t scalarSize, /*!< [in] Pointer to the size of the scalar in bytes - 120 must be equal to EC order size (for curve25519 - 32 bytes). */ 121 CCEcMontTempBuff_t *pEcMontTempBuff /*!< [in] Pointer to temp buffer, for internal use. */); 122 123 124 /*******************************************************************/ 125 /*! 126 @brief The function randomly generates private and public keys for Montgomery 127 Curve25519. it uses CC_EcMontKeyPair with the Generator point of the Curve 128 129 130 \note All byte arrays are in LE order of bytes, i.e. LS byte is on the left most place.\par 131 \note LS and MS bits of the Secret key are set according to EC Montgomery scalar mult. algorithm: 132 secrKey[0] &= 248; secrKey[31] &= 127; secrKey[31] |= 64; 133 134 @return CC_OK on success, 135 @return A non-zero value on failure as defined cc_ec_mont_edw_error.h or cc_rnd_error.h. 136 137 */ 138 CIMPORT_C CCError_t CC_EcMontKeyPair ( 139 uint8_t *pPublKey, /*!< [out] Pointer to the public key. */ 140 size_t *pPublKeySize, /*!< [in/out] Pointer to the size of the public key in bytes. 141 In - the size of the buffer must be at least EC order size 142 (for curve25519 - 32 bytes); 143 Out - the actual size. */ 144 uint8_t *pSecrKey, /*!< [out] Pointer to the secret key, including. */ 145 size_t *pSecrKeySize, /*!< [in/out] Pointer to the size of buffer for the secret key in bytes - 146 must be at least EC order size (for curve25519 - 32 bytes). */ 147 CCRndContext_t *pRndContext, /*!< [in/out] Pointer to the RND context buffer. */ 148 CCEcMontTempBuff_t *pEcMontTempBuff /*!< [in] Pointer to the temp buffer, for internal use. */); 149 150 151 /*******************************************************************/ 152 153 /*! 154 @brief The function randomly generates private and public keys for Montgomery 155 Curve25519, using a configurable base point 156 157 158 \note All byte arrays are in LE order of bytes, i.e. LS byte is on the left most place.\par 159 \note LS and MS bits of the Secret key are set according to EC Montgomery scalar mult. algorithm: 160 secrKey[0] &= 248; secrKey[31] &= 127; secrKey[31] |= 64; 161 162 @return CC_OK on success, 163 @return A non-zero value on failure as defined cc_ec_mont_edw_error.h or cc_rnd_error.h. 164 165 */ 166 CIMPORT_C CCError_t CC_EcMontKeyPairBase ( 167 uint8_t *pPublKey, /*!< [out] Pointer to the public key. */ 168 size_t *pPublKeySize, /*!< [in/out] Pointer to the size of the public key in bytes. 169 In - the size of the buffer must be at least EC order size 170 (for curve25519 - 32 bytes); 171 Out - the actual size. */ 172 uint8_t *pSecrKey, /*!< [out] Pointer to the secret key, including. */ 173 size_t *pSecrKeySize, /*!< [in/out] Pointer to the size of buffer for the secret key in bytes - 174 must be at least EC order size (for curve25519 - 32 bytes). */ 175 const uint8_t *pInPoint, /*!< [in] Pointer to the input point (compressed). */ 176 size_t inPointSize, /*!< [in] Size of the point - must be equal to CC_EC_MONT_MOD_SIZE_IN_BYTES. */ 177 CCRndContext_t *pRndContext, /*!< [in/out] Pointer to the RND context buffer. */ 178 CCEcMontTempBuff_t *pEcMontTempBuff /*!< [in] Pointer to the temp buffer, for internal use. */); 179 180 181 /*******************************************************************/ 182 183 /*! 184 @brief The function generates private and public keys for Montgomery algorithms. 185 186 The generation performed using given seed. 187 188 189 @return CC_OK on success, 190 @return A non-zero value on failure as defined cc_ec_mont_edw_error.h or cc_hash_error.h. 191 */ 192 CIMPORT_C CCError_t CC_EcMontSeedKeyPair ( 193 uint8_t *pPublKey, /*!< [out] Pointer to the public (secret) key. */ 194 size_t *pPublKeySize, /*!< [in/out] Pointer to the size of the public key in bytes. 195 In - the size of buffer must be at least EC order size 196 (for curve25519 - 32 bytes); 197 Out - the actual size. */ 198 uint8_t *pSecrKey, /*!< [out] Pointer to the secret (private) key. */ 199 size_t *pSecrKeySize, /*!< [in/out] Pointer to the size of the secret key in bytes 200 In - the size of buffer must be at least EC order size 201 (for curve25519 - 32 bytes); 202 Out - the actual size. */ 203 const uint8_t *pSeed, /*!< [in] Pointer to the given seed - 32 bytes. */ 204 size_t seedSize, /*!< [in/] Size of the seed in bytes (must be equal to CC_EC_MONT_SEEDBYTES). */ 205 CCEcMontTempBuff_t *pEcMontTempBuff /*!< [in] Pointer to a temp buffer, for internal use. */); 206 207 208 209 #ifdef __cplusplus 210 } 211 #endif 212 /** 213 @} 214 */ 215 #endif 216 217 218 219
