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_DH_H 17 #define CRYPT_DH_H 18 19 #include "hitls_build.h" 20 #ifdef HITLS_CRYPTO_DH 21 22 #include <stdint.h> 23 #include "crypt_types.h" 24 #include "crypt_algid.h" 25 #include "bsl_params.h" 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif /* __cpluscplus */ 30 31 #ifndef CRYPT_DH_TRY_CNT_MAX 32 #define CRYPT_DH_TRY_CNT_MAX 100 33 #endif 34 35 /* DH key parameter */ 36 typedef struct DH_Para CRYPT_DH_Para; 37 38 /* DH key context */ 39 typedef struct DH_Ctx CRYPT_DH_Ctx; 40 41 /** 42 * @ingroup dh 43 * @brief dh Allocate the context of dh. 44 * 45 * @retval (CRYPT_DH_Ctx *) Pointer to the memory space of the allocated context 46 * @retval NULL Invalid null pointer 47 */ 48 CRYPT_DH_Ctx *CRYPT_DH_NewCtx(void); 49 50 /** 51 * @ingroup dh 52 * @brief dh Allocate the context of dh. 53 * 54 * @param libCtx [IN] Library context 55 * 56 * @retval (CRYPT_DH_Ctx *) Pointer to the memory space of the allocated context 57 * @retval NULL Invalid null pointer 58 */ 59 CRYPT_DH_Ctx *CRYPT_DH_NewCtxEx(void *libCtx); 60 61 /** 62 * @ingroup dh 63 * @brief Copy the DH context. After the duplicated context is used up, call CRYPT_DH_FreeCtx to release the memory. 64 * 65 * @param ctx [IN] Source DH context 66 * 67 * @return CRYPT_DH_Ctx DH context pointer 68 * If the operation fails, null is returned. 69 */ 70 CRYPT_DH_Ctx *CRYPT_DH_DupCtx(CRYPT_DH_Ctx *ctx); 71 72 /** 73 * @ingroup dh 74 * @brief dh Release context structure of dh key 75 * 76 * @param ctx [IN] Indicates the pointer to the context structure to be released. The ctx is set NULL by the invoker. 77 */ 78 void CRYPT_DH_FreeCtx(CRYPT_DH_Ctx *ctx); 79 80 /** 81 * @ingroup dh 82 * @brief dh Allocate key parameter structure space 83 * 84 * @param para [IN] DH External parameter 85 * 86 * @retval (CRYPT_DH_Para *) Pointer to the memory space of the allocated context 87 * @retval NULL Invalid null pointer 88 */ 89 CRYPT_DH_Para *CRYPT_DH_NewPara(const BSL_Param *para); 90 91 /** 92 * @ingroup dh 93 * @brief Release dh key parameter structure 94 * 95 * @param para [IN] Pointer to the key parameter structure to be released. The parameter is set NULL by the invoker. 96 */ 97 void CRYPT_DH_FreePara(CRYPT_DH_Para *dhPara); 98 99 /** 100 * @ingroup dh 101 * @brief Set the data of the key parameter structure to the key structure. 102 * 103 * @param ctx [IN] Key structure for setting related parameters. The key specification is 1024-8192 bits. 104 * @param para [IN] Key parameters 105 * 106 * @retval CRYPT_NULL_INPUT Invalid null pointer input. 107 * @retval CRYPT_DH_PARA_ERROR The key parameter data is incorrect. 108 * @retval CRYPT_MEM_ALLOC_FAIL Internal Memory Allocation Error 109 * @retval BN error code: An error occurred in the internal BigNum calculation. 110 * @retval CRYPT_SUCCESS Set successfully. 111 */ 112 int32_t CRYPT_DH_SetPara(CRYPT_DH_Ctx *ctx, const BSL_Param *param); 113 114 /** 115 * @ingroup dh 116 * @brief Obtain the key structure parameters. 117 * 118 * @param ctx [IN] Key structure 119 * @param para [OUT] Obtained key parameter. 120 * 121 * @retval CRYPT_NULL_INPUT Invalid null pointer input. 122 * @retval CRYPT_DH_PARA_ERROR The key parameter data is incorrect. 123 * @retval BN error code: An error occurred in the internal BigNum calculation. 124 * @retval CRYPT_SUCCESS Set successfully. 125 */ 126 int32_t CRYPT_DH_GetPara(const CRYPT_DH_Ctx *ctx, BSL_Param *param); 127 128 /** 129 * @ingroup dh 130 * @brief Set a parameter based on the parameter ID. 131 * 132 * @param id [IN] Parameter ID 133 * 134 * @retval (CRYPT_DH_Para *) Pointer to the memory space of the allocated context 135 * @retval NULL Invalid null pointer 136 */ 137 CRYPT_DH_Para *CRYPT_DH_NewParaById(CRYPT_PKEY_ParaId id); 138 139 /** 140 * @ingroup dh 141 * @brief Obtain the parameter ID. 142 * 143 * @param ctx [IN] Key structure 144 * 145 * @retval ID. If the context is invalid, CRYPT_PKEY_PARAID_MAX is returned. 146 */ 147 CRYPT_PKEY_ParaId CRYPT_DH_GetParaId(const CRYPT_DH_Ctx *ctx); 148 149 /** 150 * @ingroup dh 151 * @brief Obtain the valid length of the key. 152 * 153 * @param ctx [IN] Structure from which the key length is expected to be obtained 154 * 155 * @retval 0 The input is incorrect or the corresponding key structure does not have a valid key length. 156 * @retval uint32_t Valid key length 157 */ 158 uint32_t CRYPT_DH_GetBits(const CRYPT_DH_Ctx *ctx); 159 160 /** 161 * @ingroup dh 162 * @brief Generate the DH key pair. 163 * 164 * @param ctx [IN] dh Context structure 165 * 166 * @retval CRYPT_NULL_INPUT Invalid null pointer input 167 * @retval CRYPT_DH_PARA_ERROR The key parameter data is incorrect. 168 * @retval CRYPT_MEM_ALLOC_FAIL Memory allocation failure 169 * @retval CRYPT_DH_RAND_GENRATE_ERROR Unable to generate results within the specified number of attempts 170 * @retval BN error code: An error occurred in the internal BigNum calculation. 171 * @retval CRYPT_SUCCESS The key pair is successfully generated. 172 */ 173 int32_t CRYPT_DH_Gen(CRYPT_DH_Ctx *ctx); 174 175 /** 176 * @ingroup dh 177 * @brief DH key exchange 178 * 179 * @param ctx [IN] dh Context structure 180 * @param pubKey [IN] Public key data 181 * @param shareKey [OUT] Shared key 182 * @param shareKeyLen [IN/OUT] The input parameter is the length of the shareKey, 183 * and the output parameter is the valid length of the shareKey. 184 * 185 * @retval CRYPT_NULL_INPUT Invalid null pointer input 186 * @retval CRYPT_DH_BUFF_LEN_NOT_ENOUGH The buffer length is insufficient. 187 * @retval CRYPT_DH_KEYINFO_ERROR The key information is incorrect. 188 * @retval CRYPT_MEM_ALLOC_FAIL Memory allocation failure 189 * @retval BN error. An error occurs in the internal BigNum operation. 190 * @retval CRYPT_SUCCESS Key exchange succeeded. 191 */ 192 int32_t CRYPT_DH_ComputeShareKey(const CRYPT_DH_Ctx *ctx, const CRYPT_DH_Ctx *pubKey, 193 uint8_t *shareKey, uint32_t *shareKeyLen); 194 195 /** 196 * @ingroup dh 197 * @brief DH Set the private key. 198 * 199 * @param ctx [OUT] dh Context structure 200 * @param para [IN] Private key 201 * 202 * @retval CRYPT_NULL_INPUT Invalid null pointer input 203 * @retval CRYPT_DH_PARA_ERROR The key parameter is incorrect. 204 * @retval CRYPT_DH_KEYINFO_ERROR The key information is incorrect. 205 * @retval CRYPT_MEM_ALLOC_FAIL Memory allocation failure 206 * @retval BN error. An error occurs in the internal BigNum operation. 207 * @retval CRYPT_SUCCESS Set successfully. 208 */ 209 int32_t CRYPT_DH_SetPrvKey(CRYPT_DH_Ctx *ctx, const BSL_Param *para); 210 211 /** 212 * @ingroup dh 213 * @brief DH Set the public key data. 214 * 215 * @param ctx [OUT] dh Context structure 216 * @param para [IN] Public key data 217 * 218 * @retval CRYPT_NULL_INPUT Error null pointer input 219 * @retval CRYPT_DH_PARA_ERROR The key parameter data is incorrect. 220 * @retval CRYPT_DH_KEYINFO_ERROR The key information is incorrect. 221 * @retval CRYPT_MEM_ALLOC_FAIL Memory allocation failure 222 * @retval BN error. An error occurs in the internal BigNum operation. 223 * @retval CRYPT_SUCCESS Set successfully. 224 */ 225 int32_t CRYPT_DH_SetPubKey(CRYPT_DH_Ctx *ctx, const BSL_Param *para); 226 227 /** 228 * @ingroup dh 229 * @brief DH Obtain the private key data. 230 * 231 * @param ctx [IN] dh Context structure 232 * @param para [OUT] Private key data 233 * 234 * @retval CRYPT_NULL_INPUT Invalid null pointer input 235 * @retval CRYPT_DH_BUFF_LEN_NOT_ENOUGH The buffer length is insufficient. 236 * @retval CRYPT_DH_KEYINFO_ERROR The key information is incorrect. 237 * @retval BN error. An error occurs in the internal BigNum operation. 238 * @retval CRYPT_SUCCESS obtained successfully. 239 */ 240 int32_t CRYPT_DH_GetPrvKey(const CRYPT_DH_Ctx *ctx, BSL_Param *para); 241 242 /** 243 * @ingroup dh 244 * @brief DH Obtain the public key data. 245 * 246 * @param ctx [IN] dh Context structure 247 * @param para [OUT] Public key data 248 * 249 * @retval CRYPT_NULL_INPUT Invalid null pointer input 250 * @retval CRYPT_DH_BUFF_LEN_NOT_ENOUGH The buffer length is insufficient. 251 * @retval CRYPT_DH_KEYINFO_ERROR The key information is incorrect. 252 * @retval BN error. An error occurs in the internal BigNum operation. 253 * @retval CRYPT_SUCCESS Obtained successfully. 254 */ 255 int32_t CRYPT_DH_GetPubKey(const CRYPT_DH_Ctx *ctx, BSL_Param *para); 256 257 258 /** 259 * @ingroup dh 260 * @brief dh Compare public keys and parameters 261 * 262 * @param a [IN] dh Context structure 263 * @param b [IN] dh Context structure 264 * 265 * @return CRYPT_SUCCESS is the same 266 * @retval CRYPT_NULL_INPUT Invalid null pointer input 267 * @retval CRYPT_DH_KEYINFO_ERROR The key information is incorrect. 268 * @retval CRYPT_DH_PUBKEY_NOT_EQUAL Public Keys are not equal 269 * @retval CRYPT_DH_PARA_ERROR The parameter data is incorrect. 270 * @retval CRYPT_DH_PARA_NOT_EQUAL The parameters are not equal. 271 */ 272 int32_t CRYPT_DH_Cmp(const CRYPT_DH_Ctx *a, const CRYPT_DH_Ctx *b); 273 274 /** 275 * @ingroup dh 276 * @brief DH control interface 277 * 278 * @param ctx [IN] dh Context structure 279 * @param opt [IN] Operation mode 280 * @param val [IN] Parameter 281 * @param len [IN] val length 282 * 283 * @retval CRYPT_NULL_INPUT Error null pointer input 284 * @retval CRYPT_SUCCESS obtained successfully. 285 */ 286 int32_t CRYPT_DH_Ctrl(CRYPT_DH_Ctx *ctx, int32_t opt, void *val, uint32_t len); 287 288 /** 289 * @ingroup dh 290 * @brief dh get security bits 291 * 292 * @param ctx [IN] dh Context structure 293 * 294 * @retval security bits 295 */ 296 int32_t CRYPT_DH_GetSecBits(const CRYPT_DH_Ctx *ctx); 297 #ifdef __cplusplus 298 } 299 #endif 300 301 #endif // HITLS_CRYPTO_DH 302 303 #endif // CRYPT_DH_H 304