1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 #ifndef CRYPT_ECDH_H 17 #define CRYPT_ECDH_H 18 19 #include "hitls_build.h" 20 #ifdef HITLS_CRYPTO_ECDH 21 22 #include <stdint.h> 23 #include "crypt_types.h" 24 #include "crypt_algid.h" 25 #include "crypt_ecc_pkey.h" 26 #include "bsl_params.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif /* __cpluscplus */ 31 32 /* ECDH key context */ 33 typedef struct ECC_PkeyCtx CRYPT_ECDH_Ctx; 34 35 /* ECDH parameter structure */ 36 typedef struct EccPara CRYPT_EcdhPara; 37 38 /** 39 * @ingroup ecdh 40 * @brief ecdh Allocate the context memory space. 41 * 42 * @retval (CRYPT_ECDH_Ctx *) Pointer to the memory space of the allocated context 43 * @retval NULL Invalid null pointer 44 */ 45 CRYPT_ECDH_Ctx *CRYPT_ECDH_NewCtx(void); 46 47 /** 48 * @ingroup ecdh 49 * @brief ecdh Allocate the context memory space. 50 * 51 * @param libCtx [IN] Library context 52 * 53 * @retval (CRYPT_ECDH_Ctx *) Pointer to the memory space of the allocated context 54 * @retval NULL Invalid null pointer 55 */ 56 CRYPT_ECDH_Ctx *CRYPT_ECDH_NewCtxEx(void *libCtx); 57 58 /** 59 * @ingroup ecdh 60 * @brief Copy the ECDH context. After the duplication is complete, call the CRYPT_ECDH_FreeCtx to release the memory. 61 * 62 * @param ctx [IN] Source ECDH context 63 * 64 * @return CRYPT_ECDH_Ctx ECDH context pointer 65 * If the operation fails, null is returned. 66 */ 67 CRYPT_ECDH_Ctx *CRYPT_ECDH_DupCtx(CRYPT_ECDH_Ctx *ctx); 68 69 /** 70 * @ingroup ecdh 71 * @brief ecdh Release the key context structure 72 * 73 * @param ctx [IN] Indicate the pointer of the context structure to be released. The ctx is set NULL by the invoker. 74 */ 75 void CRYPT_ECDH_FreeCtx(CRYPT_ECDH_Ctx *ctx); 76 77 /** 78 * @ingroup ecdh 79 * @brief Set a parameter based on the parameter ID. 80 * 81 * @param id [IN] Curve ID Parameter ID, which can be selected CRYPT_ECC_NISTP224 to CRYPT_ECC_BRAINPOOLP512R1 only 82 * from CRYPT_PKEY_ParaId. 83 * 84 * @retval (CRYPT_EcdhPara *) Pointer to the memory space of the allocated context 85 * @retval NULL Invalid null pointer 86 */ 87 CRYPT_EcdhPara *CRYPT_ECDH_NewParaById(CRYPT_PKEY_ParaId id); 88 89 /** 90 * @ingroup ecdh 91 * @brief Set a parameter based on the eccPara parameter. 92 * 93 * @param eccPara [IN] Curve parameter information, 94 * which can be selected CRYPT_ECC_NISTP224 to CRYPT_ECC_BRAINPOOLP512R1 only from the CRYPT_PKEY_ParaId. 95 * 96 * @retval (CRYPT_EcdhPara *) Pointer to the memory space of the allocated context 97 * @retval NULL Invalid null pointer 98 */ 99 CRYPT_EcdhPara *CRYPT_ECDH_NewPara(const BSL_Param *eccPara); 100 101 /** 102 * @ingroup ecdh 103 * @brief Obtain the parameter ID. 104 * 105 * @param ctx [IN] ECDH context 106 * 107 * @retval ID. If the context is invalid, CRYPT_PKEY_PARAID_MAX is returned. 108 */ 109 CRYPT_PKEY_ParaId CRYPT_ECDH_GetParaId(const CRYPT_ECDH_Ctx *ctx); 110 111 /** 112 * @ingroup ecdh 113 * @brief ecdh Release a key parameter structure 114 * 115 * @param para [IN] Pointer to the key parameter structure to be released. The parameter is set NULL by the invoker. 116 */ 117 void CRYPT_ECDH_FreePara(CRYPT_EcdhPara *para); 118 119 /** 120 * @ingroup ecdh 121 * @brief Set the data of the key parameter structure to the key structure. 122 * 123 * @param ctx [OUT] Key structure for setting related parameters 124 * @param para [IN] Key parameters 125 * 126 * @retval CRYPT_NULL_INPUT Invalid null pointer input. 127 * @retval CRYPT_MEM_ALLOC_FAIL internal memory allocation error 128 * @retval CRYPT_SUCCESS Set successfully. 129 */ 130 int32_t CRYPT_ECDH_SetPara(CRYPT_ECDH_Ctx *ctx, const BSL_Param *param); 131 132 /** 133 * @ingroup ecdh 134 * @brief Get the data of the key structure to the key parameter structure. 135 * 136 * @param ctx [IN] Key structure for setting related parameters 137 * @param param [OUT] Key parameters 138 * 139 * @retval CRYPT_NULL_INPUT Invalid null pointer input. 140 * @retval CRYPT_MEM_ALLOC_FAIL Internal memory allocation error 141 * @retval CRYPT_SUCCESS Get successfully. 142 */ 143 int32_t CRYPT_ECDH_GetPara(const CRYPT_ECDH_Ctx *ctx, BSL_Param *param); 144 145 /** 146 * @ingroup ecdh 147 * @brief Obtain the valid length of the private key, which is used before obtaining the private key. 148 * 149 * @param ctx [IN] Structure from which the key length is expected to be obtained 150 * 151 * @retval 0 The input is incorrect or the corresponding key structure does not have a valid key length. 152 * @retval uint32_t Valid key length 153 */ 154 uint32_t CRYPT_ECDH_GetBits(const CRYPT_ECDH_Ctx *ctx); 155 156 /** 157 * @ingroup ecdh 158 * @brief Generate the ECDH key pair. 159 * 160 * @param ctx [IN] ECDH Context structure 161 * 162 * @retval CRYPT_NULL_INPUT Error null pointer input 163 * @retval CRYPT_MEM_ALLOC_FAIL Memory allocation failure 164 * @retval ECC error code. Internal ECC calculation error 165 * @retval CRYPT_SUCCESS The key pair is successfully generated. 166 */ 167 int32_t CRYPT_ECDH_Gen(CRYPT_ECDH_Ctx *ctx); 168 169 /** 170 * @ingroup ecdh 171 * @brief ECDH key exchange 172 * 173 * @param ctx [IN] dh Context structure 174 * @param pubKey [IN] Public key data 175 * @param shareKey [OUT] Shared key 176 * @param shareKeyLen [IN/OUT] The input parameter is the space length of the shareKey, 177 * and the output parameter is the valid length of the shareKey. 178 * 179 * @retval CRYPT_NULL_INPUT Error null pointer input 180 * @retval CRYPT_MEM_ALLOC_FAIL Memory allocation failure 181 * @retval CRYPT_ECDH_ERR_EMPTY_KEY The ctx private key is empty or the public key pubKey is empty. 182 * @retval CRYPT_ECDH_ERR_INVALID_COFACTOR Invalid harmonic factor h 183 * @retval BN error. An error occurs in the internal BigNum operation. 184 * @retval ECC error code. Internal ECC calculation error 185 * @retval CRYPT_SUCCESS Key exchange succeeded. 186 */ 187 int32_t CRYPT_ECDH_ComputeShareKey(const CRYPT_ECDH_Ctx *ctx, const CRYPT_ECDH_Ctx *pubKey, 188 uint8_t *shareKey, uint32_t *shareKeyLen); 189 190 /** 191 * @ingroup ecdh 192 * @brief ECDH Set the private key data. 193 * 194 * @param ctx [OUT] ecdh context structure 195 * @param prv [IN] Private key data 196 * 197 * @retval CRYPT_NULL_INPUT Invalid null pointer input 198 * @retval CRYPT_MEM_ALLOC_FAIL Memory allocation failure 199 * @retval ECC error. An error occurred in the internal ECC calculation. 200 * @retval CRYPT_SUCCESS Set successfully. 201 */ 202 int32_t CRYPT_ECDH_SetPrvKey(CRYPT_ECDH_Ctx *ctx, const BSL_Param *para); 203 204 /** 205 * @ingroup ecdh 206 * @brief ECDH Set the public key data. 207 * 208 * @param ctx [OUT] ecdh context structure 209 * @param pub [IN] Public key data 210 * 211 * @retval CRYPT_NULL_INPUT Invalid null pointer input 212 * @retval CRYPT_MEM_ALLOC_FAIL Memory allocation failure 213 * @retval ECC error. An error occurred in the internal ECC calculation. 214 * @retval CRYPT_SUCCESS Set successfully. 215 */ 216 int32_t CRYPT_ECDH_SetPubKey(CRYPT_ECDH_Ctx *ctx, const BSL_Param *para); 217 218 /** 219 * @ingroup ecdh 220 * @brief ECDH Obtain the private key data. 221 * 222 * @param ctx [IN] ecdh context structure 223 * @param prv [OUT] Private key data 224 * 225 * @retval CRYPT_NULL_INPUT Invalid null pointer input 226 * @retval CRYPT_ECC_PKEY_ERR_EMPTY_KEY The key is empty. 227 * @retval ECC error. An error occurred in the internal ECC calculation. 228 * @retval CRYPT_SUCCESS Obtained successfully. 229 */ 230 int32_t CRYPT_ECDH_GetPrvKey(const CRYPT_ECDH_Ctx *ctx, BSL_Param *para); 231 232 /** 233 * @ingroup ecdh 234 * @brief ECDH Obtain the public key data. 235 * 236 * @param ctx [IN] ecdh context structure 237 * @param pub [OUT] Public key data 238 * 239 * @retval CRYPT_NULL_INPUT Invalid null pointer input 240 * @retval CRYPT_ECC_PKEY_ERR_EMPTY_KEY The key is empty. 241 * @retval ECC error. An error occurred in the internal ECC calculation. 242 * @retval CRYPT_SUCCESS Obtained successfully. 243 */ 244 int32_t CRYPT_ECDH_GetPubKey(const CRYPT_ECDH_Ctx *ctx, BSL_Param *para); 245 246 /** 247 * @ingroup ecdh 248 * @brief ecdh control interface 249 * 250 * @param ctx [IN/OUT] ecdh context structure 251 * @param opt [IN] Operation mode. For details, see ECC_CtrlType. 252 * @param val [IN] Input parameter about ctrl 253 * @param len [IN] val Length 254 * 255 * @retval CRYPT_SUCCESS Set successfully. 256 * @retval CRYPT_NULL_INPUT If any input parameter is empty 257 * @retval CRYPT_ECC_PKEY_ERR_INVALID_POINT_FORMAT Invalid point format 258 * @retval CRYPT_ECC_PKEY_ERR_CTRL_LEN The len is incorrect. 259 * @retval CRYPT_ECC_PKEY_ERR_UNSUPPORTED_CTRL_OPTION opt mode not supported 260 */ 261 int32_t CRYPT_ECDH_Ctrl(CRYPT_ECDH_Ctx *ctx, int32_t opt, void *val, uint32_t len); 262 263 /** 264 * @ingroup ecdh 265 * @brief ecdh Compare public keys and parameters 266 * 267 * @param a [IN] ecdh context structure 268 * @param b [IN] ecdh context structure 269 * 270 * @retval CRYPT_SUCCESS is the same 271 * Others. For details, see errno. 272 */ 273 int32_t CRYPT_ECDH_Cmp(const CRYPT_ECDH_Ctx *a, const CRYPT_ECDH_Ctx *b); 274 275 /** 276 * @ingroup ecdh 277 * @brief ecdh get security bits 278 * 279 * @param ctx [IN] ecdh Context structure 280 * 281 * @retval security bits 282 */ 283 int32_t CRYPT_ECDH_GetSecBits(const CRYPT_ECDH_Ctx *ctx); 284 285 #ifdef __cplusplus 286 } 287 #endif 288 289 #endif // HITLS_CRYPTO_ECDH 290 291 #endif // CRYPT_ECDH_H 292