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_DEFAULT_H 17 #define CRYPT_DEFAULT_H 18 #include <stdint.h> 19 #include "hitls_crypt_type.h" 20 #include "hitls_crypt_reg.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * @brief Generate a random number. 28 * 29 * @param buf [OUT] Random number 30 * @param len [IN] Random number length 31 * 32 * @retval HITLS_SUCCESS succeeded. 33 * @retval Other failure 34 */ 35 int32_t CRYPT_DEFAULT_RandomBytes(uint8_t *buf, uint32_t len); 36 37 /** 38 * @brief Obtain the HMAC length. 39 * 40 * @param hashAlgo [IN] hash algorithm 41 * 42 * @return HMAC length 43 */ 44 uint32_t CRYPT_DEFAULT_HMAC_Size(HITLS_HashAlgo hashAlgo); 45 46 /** 47 * @brief Initialize the HMAC context. 48 * 49 * @param hashAlgo [IN] Hash algorithm 50 * @param key [IN] Key 51 * @param len [IN] Key length 52 * 53 * @return HMAC context 54 */ 55 HITLS_HMAC_Ctx *CRYPT_DEFAULT_HMAC_Init(HITLS_HashAlgo hashAlgo, const uint8_t *key, uint32_t len); 56 57 /** 58 * @brief ReInitialize the HMAC context. 59 * 60 * @param ctx [IN] HMAC context. 61 * 62 * @retval HITLS_SUCCESS succeeded. 63 * @retval Other failure 64 */ 65 int32_t CRYPT_DEFAULT_HMAC_ReInit(HITLS_HMAC_Ctx *ctx); 66 67 /** 68 * @brief Release the HMAC context. 69 * 70 * @param hmac [IN] HMAC context. The CTX is set NULL by the invoker. 71 */ 72 void CRYPT_DEFAULT_HMAC_Free(HITLS_HMAC_Ctx *ctx); 73 74 /** 75 * @brief Add the HMAC input data. 76 * 77 * @param hmac [IN] HMAC context 78 * @param data [IN] Input data 79 * @param len [IN] Input data length 80 * 81 * @retval HITLS_SUCCESS succeeded. 82 * @retval Other failure 83 */ 84 int32_t CRYPT_DEFAULT_HMAC_Update(HITLS_HMAC_Ctx *ctx, const uint8_t *data, uint32_t len); 85 86 /** 87 * @brief HMAC calculation result 88 * 89 * @param hmac [IN] HMAC context 90 * @param out [OUT] Output data 91 * @param len [IN/OUT] IN: Maximum length of data padding OUT: Output data length 92 * 93 * @retval HITLS_SUCCESS succeeded. 94 * @retval Other failure 95 */ 96 int32_t CRYPT_DEFAULT_HMAC_Final(HITLS_HMAC_Ctx *ctx, uint8_t *out, uint32_t *len); 97 98 /** 99 * @brief HMAC function 100 * 101 * @param hashAlgo [IN] Hash algorithm 102 * @param key [IN] Key 103 * @param keyLen [IN] Key length 104 * @param in [IN] Input data 105 * @param inLen [IN] Input data length 106 * @param out [OUT] Output data 107 * @param outLen [IN/OUT] IN: Maximum length of data padding OUT: Output data length 108 * 109 * @retval HITLS_SUCCESS succeeded. 110 * @retval Other failure 111 */ 112 int32_t CRYPT_DEFAULT_HMAC(HITLS_HashAlgo hashAlgo, const uint8_t *key, uint32_t keyLen, 113 const uint8_t *in, uint32_t inLen, uint8_t *out, uint32_t *outLen); 114 115 /** 116 * @brief Obtain the hash length. 117 * 118 * @param hashAlgo [IN] hash algorithm 119 * 120 * @return Hash length 121 */ 122 uint32_t CRYPT_DEFAULT_DigestSize(HITLS_HashAlgo hashAlgo); 123 124 /** 125 * @brief Initialize the hash context. 126 * 127 * @param hashAlgo [IN] Hash algorithm 128 * 129 * @return hash context 130 */ 131 HITLS_HASH_Ctx *CRYPT_DEFAULT_DigestInit(HITLS_HashAlgo hashAlgo); 132 133 /** 134 * @brief Copy the hash context. 135 * 136 * @param ctx [IN] hash context 137 * 138 * @return hash context 139 */ 140 HITLS_HASH_Ctx *CRYPT_DEFAULT_DigestCopy(HITLS_HASH_Ctx *ctx); 141 142 /** 143 * @brief Release the hash context. 144 * 145 * @param ctx [IN] Hash context. The CTX is set NULL by the invoker. 146 */ 147 void CRYPT_DEFAULT_DigestFree(HITLS_HASH_Ctx *ctx); 148 149 /** 150 * @brief Add the hash input data. 151 * 152 * @param ctx [IN] hash Context 153 * @param data [IN] Input data 154 * @param len [IN] Length of the input data 155 * 156 * @retval HITLS_SUCCESS succeeded. 157 * @retval Other failure 158 */ 159 int32_t CRYPT_DEFAULT_DigestUpdate(HITLS_HASH_Ctx *ctx, const uint8_t *data, uint32_t len); 160 161 /** 162 * @brief Calculate the hash result. 163 * 164 * @param ctx [IN] hash context 165 * @param out [OUT] Output data 166 * @param len [IN/OUT] IN: Maximum length of data padding OUT: Length of output data 167 * 168 * @retval HITLS_SUCCESS succeeded. 169 * @retval Other failure 170 */ 171 int32_t CRYPT_DEFAULT_DigestFinal(HITLS_HASH_Ctx *ctx, uint8_t *out, uint32_t *len); 172 173 /** 174 * @brief hash function 175 * 176 * @param hashAlgo [IN] hash algorithm 177 * @param in [IN] Input data 178 * @param inLen [IN] Input data length 179 * @param out [OUT] Output data 180 * @param outLen [IN/OUT] IN: Maximum length of data padding OUT: Output data length 181 * 182 * @retval HITLS_SUCCESS succeeded. 183 * @retval Other failure 184 */ 185 int32_t CRYPT_DEFAULT_Digest(HITLS_HashAlgo hashAlgo, const uint8_t *in, uint32_t inLen, 186 uint8_t *out, uint32_t *outLen); 187 188 /** 189 * @brief Encryption 190 * 191 * @param cipher [IN] Key parameters 192 * @param in [IN] Plaintext data 193 * @param inLen [IN] Length of the plaintext data 194 * @param out [OUT] Ciphertext data 195 * @param outLen [IN/OUT] IN: Maximum length of data padding OUT: Length of ciphertext data 196 * 197 * @retval HITLS_SUCCESS succeeded. 198 * @retval Other failure 199 */ 200 int32_t CRYPT_DEFAULT_Encrypt(const HITLS_CipherParameters *cipher, const uint8_t *in, uint32_t inLen, 201 uint8_t *out, uint32_t *outLen); 202 203 /** 204 * @brief Decrypt 205 * 206 * @param cipher [IN] Key parameters 207 * @param in [IN] Ciphertext data 208 * @param inLen [IN] Length of the ciphertext data 209 * @param out [OUT] Plaintext data 210 * @param outLen [IN/OUT] IN: Maximum length of data padding OUT: Length of plaintext data 211 * 212 * @retval HITLS_SUCCESS succeeded. 213 * @retval Other failure 214 */ 215 int32_t CRYPT_DEFAULT_Decrypt(const HITLS_CipherParameters *cipher, const uint8_t *in, uint32_t inLen, 216 uint8_t *out, uint32_t *outLen); 217 218 /** 219 * @brief Release the cipher ctx. 220 * 221 * @param ctx [IN] cipher ctx handle. The handle is set NULL by the invoker. 222 */ 223 void CRYPT_DEFAULT_CipherFree(HITLS_Cipher_Ctx *ctx); 224 /** 225 * @brief Generate the ECDH key pair. 226 * 227 * @param curveParams [IN] ECDH parameter 228 * 229 * @return Key handle 230 */ 231 HITLS_CRYPT_Key *CRYPT_DEFAULT_GenerateEcdhKey(const HITLS_ECParameters *curveParams); 232 233 /** 234 * @brief Generate a DH key pair. 235 * 236 * @param secbits [IN] Key security level 237 * 238 * @return Key handle 239 */ 240 HITLS_CRYPT_Key *CRYPT_DEFAULT_GenerateDhKeyBySecbits(int32_t secbits); 241 242 /** 243 * @brief Generate a DH key pair. 244 * 245 * @param p [IN] p Parameter 246 * @param plen [IN] p Parameter length 247 * @param g [IN] g Parameter 248 * @param glen [IN] g Parameter length 249 * 250 * @return Key handle 251 */ 252 HITLS_CRYPT_Key *CRYPT_DEFAULT_GenerateDhKeyByParameters(uint8_t *p, uint16_t pLen, uint8_t *g, uint16_t gLen); 253 254 /** 255 * @brief Obtain the DH parameter. 256 * 257 * @param key [IN] Key handle 258 * @param p [OUT] p Parameter 259 * @param plen [IN/OUT] IN: Maximum length of data padding OUT: p Parameter length 260 * @param g [OUT] g Parameter 261 * @param glen [IN/OUT] IN: Maximum length of data padding OUT: g Parameter length 262 * 263 * @retval HITLS_SUCCESS succeeded. 264 * @retval Other failure 265 */ 266 int32_t CRYPT_DEFAULT_GetDhParameters(HITLS_CRYPT_Key *key, uint8_t *p, uint16_t *pLen, uint8_t *g, uint16_t *gLen); 267 268 /** 269 * @brief Deep copy key 270 * 271 * @param key [IN] Key handle 272 * @retval Key handle 273 */ 274 HITLS_CRYPT_Key *CRYPT_DEFAULT_DupKey(HITLS_CRYPT_Key *key); 275 276 /** 277 * @brief Release the key. 278 * 279 * @param key [IN] Key handle. The key is set NULL by the invoker. 280 */ 281 void CRYPT_DEFAULT_FreeKey(HITLS_CRYPT_Key *key); 282 283 /** 284 * @brief Obtain the public key data. 285 * 286 * @param key [IN] Key handle 287 * @param pubKeyBuf [OUT] Public key data 288 * @param bufLen [IN] Maximum length of data padding. 289 * @param usedLen [OUT] Public key data length 290 * 291 * @retval HITLS_SUCCESS succeeded. 292 * @retval Other failure 293 */ 294 int32_t CRYPT_DEFAULT_GetPubKey(HITLS_CRYPT_Key *key, uint8_t *pubKeyBuf, uint32_t bufLen, uint32_t *pubKeyLen); 295 296 /** 297 * @brief Calculate the shared key. Ref RFC 5246 section 8.1.2, this interface will remove the pre-zeros. 298 * 299 * @param key [IN] Local key handle 300 * @param peerPubkey [IN] Peer public key data 301 * @param pubKeyLen [IN] Public key data length 302 * @param sharedSecret [OUT] Shared key 303 * @param sharedSecretLen [IN/OUT] IN: Maximum length of data padding OUT: length of the shared key 304 * 305 * @retval HITLS_SUCCESS succeeded. 306 * @retval Other failure 307 */ 308 int32_t CRYPT_DEFAULT_DhCalcSharedSecret(HITLS_CRYPT_Key *key, uint8_t *peerPubkey, uint32_t pubKeyLen, 309 uint8_t *sharedSecret, uint32_t *sharedSecretLen); 310 311 /** 312 * @brief Calculate the shared key. Ref RFC 8446 section 7.4.1, this interface will retain the leading zeros. 313 * after calculation. 314 * 315 * @param key [IN] Local key handle 316 * @param peerPubkey [IN] Peer public key data 317 * @param pubKeyLen [IN] Public key data length 318 * @param sharedSecret [OUT] Shared key 319 * @param sharedSecretLen [IN/OUT] IN: Maximum length of data padding OUT: length of the shared key 320 * 321 * @retval HITLS_SUCCESS succeeded. 322 * @retval Other failure 323 */ 324 int32_t CRYPT_DEFAULT_EcdhCalcSharedSecret(HITLS_CRYPT_Key *key, uint8_t *peerPubkey, uint32_t pubKeyLen, 325 uint8_t *sharedSecret, uint32_t *sharedSecretLen); 326 327 /** 328 * @brief Calculate the SM2 shared key. 329 * 330 * @param sm2Params [IN] SM2 parameters 331 * @param sharedSecret [OUT] Shared key 332 * @param sharedSecretLen [IN/OUT] IN: Maximum length of data padding OUT: length of the shared key 333 * 334 * @retval HITLS_SUCCESS 335 * @retval Other failure 336 */ 337 int32_t CRYPT_DEFAULT_CalcSM2SharedSecret(HITLS_Sm2GenShareKeyParameters *sm2Params, 338 uint8_t *sharedSecret, uint32_t *sharedSecretLen); 339 340 /** 341 * @brief HKDF-Extract 342 * 343 * @param input [IN] Input key material. 344 * @param prk [OUT] Output key 345 * @param prkLen [IN/OUT] IN: Maximum buffer length OUT: Output key length 346 * 347 * @retval HITLS_SUCCESS succeeded. 348 * @retval Other failure 349 */ 350 int32_t CRYPT_DEFAULT_HkdfExtract(const HITLS_CRYPT_HkdfExtractInput *input, uint8_t *prk, uint32_t *prkLen); 351 352 /** 353 * @brief HKDF-Expand 354 * 355 * @param input [IN] Input key material. 356 * @param okm [OUT] Output key 357 * @param okmLen [IN] Output key length 358 * 359 * @retval HITLS_SUCCESS succeeded. 360 * @retval Other failure 361 */ 362 int32_t CRYPT_DEFAULT_HkdfExpand(const HITLS_CRYPT_HkdfExpandInput *input, uint8_t *okm, uint32_t okmLen); 363 364 /** 365 * @brief Initialize the hash context. 366 * 367 * This function initializes the hash context with the given hash algorithm. 368 * 369 * @param hashAlgo [IN] Hash algorithm to be used in the hash operation, e.g., HITLS_SHA256. 370 * 371 * @return hash context 372 * Returns a pointer to the initialized hash context. 373 * Returns NULL if the initialization fails. 374 */ 375 HITLS_HASH_Ctx *CRYPT_DEFAULT_DigestInit(HITLS_HashAlgo hashAlgo); 376 377 /** 378 * @brief KEM-Encapsulate 379 * 380 * @param params [IN] KEM encapsulation parameters 381 * 382 * @retval HITLS_SUCCESS succeeded. 383 */ 384 int32_t CRYPT_DEFAULT_KemEncapsulate(HITLS_KemEncapsulateParams *params); 385 386 /** 387 * @brief KEM-Decapsulate 388 * 389 * @param key [IN] Key handle 390 * @param ciphertext [IN] Ciphertext data 391 * @param ciphertextLen [IN] Ciphertext data length 392 * @param sharedSecret [OUT] Shared key 393 * @param sharedSecretLen [IN/OUT] IN: Maximum length of data padding OUT: length of the shared key 394 * 395 * @retval HITLS_SUCCESS succeeded. 396 * @retval Other failure 397 */ 398 int32_t CRYPT_DEFAULT_KemDecapsulate(HITLS_CRYPT_Key *key, const uint8_t *ciphertext, uint32_t ciphertextLen, 399 uint8_t *sharedSecret, uint32_t *sharedSecretLen); 400 401 #ifdef __cplusplus 402 } 403 #endif 404 #endif