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 HITLS_CRYPT_H 17 #define HITLS_CRYPT_H 18 #include <stdint.h> 19 #include "hitls_crypt_type.h" 20 #include "hitls_crypt_reg.h" 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /** 26 * @brief Initialize the HMAC context. 27 * 28 * This function initializes the HMAC (Hash-based Message Authentication Code) context 29 * with the given library context, attribute name, hash algorithm, key, and key length. 30 * 31 * @param libCtx [IN] Library context, used to manage cryptographic operations. 32 * @param attrName [IN] Attribute name, which may be used for specific configuration. 33 * @param hashAlgo [IN] Hash algorithm to be used in the HMAC operation, e.g., HITLS_SHA256. 34 * @param key [IN] Secret key used for HMAC calculation. 35 * @param len [IN] Length of the secret key in bytes. 36 * 37 * @return HMAC context 38 * Returns a pointer to the initialized HMAC context. 39 * Returns NULL if the initialization fails. 40 */ 41 HITLS_HMAC_Ctx *HITLS_CRYPT_HMAC_Init(HITLS_Lib_Ctx *libCtx, const char *attrName, 42 HITLS_HashAlgo hashAlgo, const uint8_t *key, uint32_t len); 43 44 /** 45 * @brief Perform HMAC calculation. 46 * 47 * This function calculates the HMAC (Hash-based Message Authentication Code) 48 * using the given library context, attribute name, hash algorithm, key, input data, 49 * and stores the result in the output buffer. 50 * 51 * @param libCtx [IN] Library context, used to manage cryptographic operations. 52 * @param attrName [IN] Attribute name, which may be used for specific configuration. 53 * @param hashAlgo [IN] Hash algorithm to be used in the HMAC operation, e.g., HITLS_SHA256. 54 * @param key [IN] Secret key used for HMAC calculation. 55 * @param keyLen [IN] Length of the secret key in bytes. 56 * @param in [IN] Input data to be processed for HMAC calculation. 57 * @param inLen [IN] Length of the input data in bytes. 58 * @param out [OUT] Buffer to store the calculated HMAC output. 59 * @param outLen [IN/OUT] IN: Maximum length of the output buffer. OUT: Actual length of the calculated HMAC output. 60 * 61 * @retval HITLS_SUCCESS succeeded. 62 * @retval Other failure 63 */ 64 int32_t HITLS_CRYPT_HMAC(HITLS_Lib_Ctx *libCtx, const char *attrName, HITLS_HashAlgo hashAlgo, const uint8_t *key, 65 uint32_t keyLen, const uint8_t *in, uint32_t inLen, uint8_t *out, uint32_t *outLen); 66 67 /** 68 * @brief Perform hash calculation. 69 * 70 * This function calculates the hash of the input data using the given library context, 71 * attribute name, hash algorithm, and stores the result in the output buffer. 72 * 73 * @param libCtx [IN] Library context, used to manage cryptographic operations. 74 * @param attrName [IN] Attribute name, which may be used for specific configuration. 75 * @param hashAlgo [IN] Hash algorithm to be used in the hash operation, e.g., HITLS_SHA256. 76 * @param in [IN] Input data to be processed for hash calculation. 77 * @param inLen [IN] Length of the input data in bytes. 78 * @param out [OUT] Buffer to store the calculated hash output. 79 * @param outLen [IN/OUT] IN: Maximum length of the output buffer. OUT: Actual length of the calculated hash output. 80 * 81 * @retval HITLS_SUCCESS succeeded. 82 * @retval Other failure 83 */ 84 int32_t HITLS_CRYPT_Digest(HITLS_Lib_Ctx *libCtx, const char *attrName, HITLS_HashAlgo hashAlgo, const uint8_t *in, 85 uint32_t inLen, uint8_t *out, uint32_t *outLen); 86 87 /** 88 * @brief Perform encryption operation. 89 * 90 * This function encrypts the input data using the given library context, attribute name, 91 * cipher parameters, and stores the encrypted data in the output buffer. 92 * 93 * @param libCtx [IN] Library context, used to manage cryptographic operations. 94 * @param attrName [IN] Attribute name, which may be used for specific configuration. 95 * @param cipher [IN] Key parameters for the encryption operation. 96 * @param in [IN] Plaintext data to be encrypted. 97 * @param inLen [IN] Length of the plaintext data in bytes. 98 * @param out [OUT] Buffer to store the encrypted data (ciphertext). 99 * @param outLen [IN/OUT] IN: Maximum length of the output buffer. OUT: Actual length of the encrypted data. 100 * 101 * @retval HITLS_SUCCESS succeeded. 102 * @retval Other failure 103 */ 104 int32_t HITLS_CRYPT_Encrypt(HITLS_Lib_Ctx *libCtx, const char *attrName, const HITLS_CipherParameters *cipher, 105 const uint8_t *in, uint32_t inLen, uint8_t *out, uint32_t *outLen); 106 107 /** 108 * @brief Perform decryption operation. 109 * 110 * This function decrypts the input ciphertext using the given library context, attribute name, 111 * cipher parameters, and stores the decrypted data in the output buffer. 112 * 113 * @param libCtx [IN] Library context, used to manage cryptographic operations. 114 * @param attrName [IN] Attribute name, which may be used for specific configuration. 115 * @param cipher [IN] Key parameters for the decryption operation. 116 * @param in [IN] Ciphertext data to be decrypted. 117 * @param inLen [IN] Length of the ciphertext data in bytes. 118 * @param out [OUT] Buffer to store the decrypted data (plaintext). 119 * @param outLen [IN/OUT] IN: Maximum length of the output buffer. OUT: Actual length of the decrypted data. 120 * 121 * @retval HITLS_SUCCESS succeeded. 122 * @retval Other failure 123 */ 124 int32_t HITLS_CRYPT_Decrypt(HITLS_Lib_Ctx *libCtx, const char *attrName, const HITLS_CipherParameters *cipher, 125 const uint8_t *in, uint32_t inLen, uint8_t *out, uint32_t *outLen); 126 127 /** 128 * @brief Generate an ECDH key pair. 129 * 130 * This function generates an ECDH (Elliptic Curve Diffie-Hellman) key pair 131 * using the given library context, attribute name, configuration, and curve parameters. 132 * 133 * @param libCtx [IN] Library context, used to manage cryptographic operations. 134 * @param attrName [IN] Attribute name, which may be used for specific configuration. 135 * @param config [IN] Configuration for the ECDH key generation. 136 * @param curveParams [IN] ECDH parameter specifying the elliptic curve. 137 * 138 * @return Key handle 139 * Returns a pointer to the generated ECDH key handle. 140 * Returns NULL if the key generation fails. 141 */ 142 HITLS_CRYPT_Key *HITLS_CRYPT_GenerateEcdhKey(HITLS_Lib_Ctx *libCtx, const char *attrName, 143 const HITLS_Config *config, const HITLS_ECParameters *curveParams); 144 145 146 /** 147 * @brief Calculate the shared secret. 148 * 149 * This function calculates the shared secret using the given library context, attribute name, local key handle, 150 * peer public key data, and its length. Ref RFC 5246 section 8.1.2, this interface will remove the pre-zeros. 151 * 152 * @param libCtx [IN] Library context, used to manage cryptographic operations. 153 * @param attrName [IN] Attribute name, which may be used for specific configuration. 154 * @param key [IN] Local key handle. 155 * @param peerPubkey [IN] Peer public key data. 156 * @param pubKeyLen [IN] Length of the peer public key data. 157 * @param sharedSecret [OUT] Buffer to store the shared secret. 158 * @param sharedSecretLen [IN/OUT] IN: Maximum length of the buffer. OUT: Actual length of the shared secret. 159 * 160 * @retval HITLS_SUCCESS Succeeded. 161 * @retval Other Failed. 162 */ 163 int32_t HITLS_CRYPT_DhCalcSharedSecret(HITLS_Lib_Ctx *libCtx, const char *attrName, HITLS_CRYPT_Key *key, 164 uint8_t *peerPubkey, uint32_t pubKeyLen, uint8_t *sharedSecret, uint32_t *sharedSecretLen); 165 166 /** 167 * @brief Calculate the shared secret. 168 * 169 * This function calculates the shared secret using the given library context, attribute name, local key handle, 170 * peer public key data, and its length. Ref RFC 8446 section 7.4.1, this interface will retain the leading zeros. 171 * 172 * @param libCtx [IN] Library context, used to manage cryptographic operations. 173 * @param attrName [IN] Attribute name, which may be used for specific configuration. 174 * @param key [IN] Local key handle. 175 * @param peerPubkey [IN] Peer public key data. 176 * @param pubKeyLen [IN] Length of the peer public key data. 177 * @param sharedSecret [OUT] Buffer to store the shared secret. 178 * @param sharedSecretLen [IN/OUT] IN: Maximum length of the buffer. OUT: Actual length of the shared secret. 179 * 180 * @retval HITLS_SUCCESS Succeeded. 181 * @retval Other Failed. 182 */ 183 int32_t HITLS_CRYPT_EcdhCalcSharedSecret(HITLS_Lib_Ctx *libCtx, const char *attrName, HITLS_CRYPT_Key *key, 184 uint8_t *peerPubkey, uint32_t pubKeyLen, uint8_t *sharedSecret, uint32_t *sharedSecretLen); 185 186 /** 187 * @brief Calculate the SM2 shared secret. 188 * 189 * This function calculates the SM2 shared secret using the given library context, attribute name, and SM2 parameters. 190 * 191 * @param libCtx [IN] Library context, used to manage cryptographic operations. 192 * @param attrName [IN] Attribute name, which may be used for specific configuration. 193 * @param sm2Params [IN] Parameters for SM2 shared key generation. 194 * @param sharedSecret [OUT] Buffer to store the shared secret. 195 * @param sharedSecretLen [IN/OUT] IN: Maximum length of the buffer. OUT: Actual length of the shared secret. 196 * 197 * @retval HITLS_SUCCESS Succeeded. 198 * @retval Other Failed. 199 */ 200 int32_t HITLS_CRYPT_CalcSM2SharedSecret(HITLS_Lib_Ctx *libCtx, const char *attrName, 201 HITLS_Sm2GenShareKeyParameters *sm2Params, uint8_t *sharedSecret, uint32_t *sharedSecretLen); 202 203 /** 204 * @brief Generate a DH key pair based on the security level. 205 * 206 * This function generates a DH key pair using the given library context, attribute name, configuration, and named group ID. 207 * 208 * @param libCtx [IN] Library context, used to manage cryptographic operations. 209 * @param attrName [IN] Attribute name, which may be used for specific configuration. 210 * @param tlsConfig [IN] TLS configuration. 211 * @param secBits [IN] Security level. 212 * 213 * @return Key handle 214 * Returns a pointer to the generated DH key pair handle. 215 * Returns NULL if the key generation fails. 216 */ 217 HITLS_CRYPT_Key *HITLS_CRYPT_GenerateDhKeyBySecbits(HITLS_Lib_Ctx *libCtx, const char *attrName, 218 const HITLS_Config *tlsConfig, int32_t secBits); 219 220 /** 221 * @brief Generate a DH key pair based on parameters. 222 * 223 * This function generates a DH key pair using the given library context, attribute name, p parameter, and g parameter. 224 * 225 * @param libCtx [IN] Library context, used to manage cryptographic operations. 226 * @param attrName [IN] Attribute name, which may be used for specific configuration. 227 * @param p [IN] p parameter. 228 * @param pLen [IN] Length of the p parameter. 229 * @param g [IN] g parameter. 230 * @param gLen [IN] Length of the g parameter. 231 * 232 * @return Key handle 233 * Returns a pointer to the generated DH key pair handle. 234 * Returns NULL if the key generation fails. 235 */ 236 HITLS_CRYPT_Key *HITLS_CRYPT_GenerateDhKeyByParameters(HITLS_Lib_Ctx *libCtx, 237 const char *attrName, uint8_t *p, uint16_t pLen, uint8_t *g, uint16_t gLen); 238 239 /** 240 * @brief HKDF expand function. 241 * 242 * This function performs the HKDF expand operation using the given library context, attribute name, and HKDF expand input. 243 * 244 * @param libCtx [IN] Library context, used to manage cryptographic operations. 245 * @param attrName [IN] Attribute name, which may be used for specific configuration. 246 * @param input [IN] HKDF expand input. 247 * @param okm [OUT] Buffer to store the output key. 248 * @param okmLen [IN] Length of the output key. 249 * 250 * @retval HITLS_SUCCESS Succeeded. 251 * @retval Other Failed. 252 */ 253 int32_t HITLS_CRYPT_HkdfExpand(HITLS_Lib_Ctx *libCtx, const char *attrName, const HITLS_CRYPT_HkdfExpandInput *input, 254 uint8_t *okm, uint32_t okmLen); 255 256 /** 257 * @brief HKDF extract function. 258 * 259 * This function performs the HKDF extract operation using the given library context, attribute name, and HKDF extract input. 260 * 261 * @param libCtx [IN] Library context, used to manage cryptographic operations. 262 * @param attrName [IN] Attribute name, which may be used for specific configuration. 263 * @param input [IN] HKDF extract input. 264 * @param prk [OUT] Buffer to store the output key. 265 * @param prkLen [IN/OUT] IN: Maximum length of the buffer. OUT: Actual length of the output key. 266 * 267 * @retval HITLS_SUCCESS Succeeded. 268 * @retval Other Failed. 269 */ 270 int32_t HITLS_CRYPT_HkdfExtract(HITLS_Lib_Ctx *libCtx, const char *attrName, const HITLS_CRYPT_HkdfExtractInput *input, 271 uint8_t *prk, uint32_t *prkLen); 272 273 /** 274 * @brief Generate a sequence of random bytes of the specified length. 275 * 276 * This function is used to generate a sequence of random bytes of the specified length 277 * and store it in the provided buffer. It uses the passed library context for random number generation. 278 * 279 * @param libCtx [IN] Library context, used to manage cryptographic operations. 280 * @param bytes [OUT] Buffer used to store the generated random byte sequence. 281 * @param bytesLen [IN] Length (in bytes) of the random byte sequence to be generated. 282 * 283 * @retval Returns HITLS_SUCCESS on success, and other error codes on failure. 284 */ 285 int32_t HITLS_CRYPT_RandbytesEx(HITLS_Lib_Ctx *libCtx, uint8_t *bytes, uint32_t bytesLen); 286 287 /** 288 * @brief Initialize the hash context. 289 * 290 * This function initializes the hash context with the given library context, attribute name, and hash algorithm. 291 * 292 * @param libCtx [IN] Library context, used to manage cryptographic operations. 293 * @param attrName [IN] Attribute name, which may be used for specific configuration. 294 * @param hashAlgo [IN] Hash algorithm to be used in the hash operation, e.g., HITLS_SHA256. 295 */ 296 HITLS_HASH_Ctx *HITLS_CRYPT_DigestInit(HITLS_Lib_Ctx *libCtx, const char *attrName, HITLS_HashAlgo hashAlgo); 297 298 /** 299 * @brief Free DH key structure. 300 * 301 * @param key [IN] Pointer to DH key structure to be freed. 302 */ 303 void HITLS_CRYPT_FreeKey(HITLS_CRYPT_Key *key); 304 305 /** 306 * @brief Get DH parameters from key. 307 * 308 * @param key [IN] DH key structure. 309 * @param p [OUT] Prime modulus parameter. 310 * @param pLen [IN/OUT] IN: Buffer length, OUT: Actual length of prime modulus. 311 * @param g [OUT] Generator parameter. 312 * @param gLen [IN/OUT] IN: Buffer length, OUT: Actual length of generator. 313 * 314 * @retval HITLS_SUCCESS Succeeded. 315 * @retval Other Failed. 316 */ 317 int32_t HITLS_CRYPT_GetDhParameters(HITLS_CRYPT_Key *key, uint8_t *p, uint16_t *pLen, uint8_t *g, uint16_t *gLen); 318 319 320 /** 321 * @brief Reinitialize an HMAC context for reuse. 322 * 323 * @param ctx [IN] HMAC context to reinitialize. 324 * @retval HITLS_SUCCESS Reinitialization succeeded. 325 * @retval Other Failed to reinitialize context. 326 */ 327 int32_t HITLS_CRYPT_HMAC_ReInit(HITLS_HMAC_Ctx *ctx); 328 329 /** 330 * @brief Free an HMAC context. 331 * 332 * @param ctx [IN] HMAC context to free. 333 */ 334 void HITLS_CRYPT_HMAC_Free(HITLS_HMAC_Ctx *ctx); 335 336 /** 337 * @brief Update HMAC computation with input data. 338 * 339 * @param ctx [IN] HMAC context. 340 * @param data [IN] Input data to process. 341 * @param len [IN] Length of input data in bytes. 342 * @retval HITLS_SUCCESS Update succeeded. 343 * @retval Other Failed to update HMAC. 344 */ 345 int32_t HITLS_CRYPT_HMAC_Update(HITLS_HMAC_Ctx *ctx, const uint8_t *data, uint32_t len); 346 347 /** 348 * @brief Finalize HMAC computation and get the MAC value. 349 * 350 * @param ctx [IN] HMAC context. 351 * @param out [OUT] Buffer to store the MAC value. 352 * @param len [IN/OUT] IN: Buffer size, OUT: Actual MAC length. 353 * @retval HITLS_SUCCESS Finalization succeeded. 354 * @retval Other Failed to finalize HMAC. 355 */ 356 int32_t HITLS_CRYPT_HMAC_Final(HITLS_HMAC_Ctx *ctx, uint8_t *out, uint32_t *len); 357 358 /** 359 * @brief Get the output size of a hash algorithm. 360 * 361 * @param hashAlgo [IN] Hash algorithm identifier. 362 * @return Digest size in bytes. Returns 0 for unsupported algorithms. 363 */ 364 uint32_t HITLS_CRYPT_DigestSize(HITLS_HashAlgo hashAlgo); 365 366 /** 367 * @brief Create a copy of a hash context. 368 * 369 * @param ctx [IN] Original hash context to copy. 370 * @return New hash context copy. Returns NULL on failure. 371 */ 372 HITLS_HASH_Ctx *HITLS_CRYPT_DigestCopy(HITLS_HASH_Ctx *ctx); 373 374 /** 375 * @brief Free a hash context. 376 * 377 * @param ctx [IN] Hash context to free. 378 */ 379 void HITLS_CRYPT_DigestFree(HITLS_HASH_Ctx *ctx); 380 381 /** 382 * @brief Update hash computation with input data. 383 * 384 * @param ctx [IN] Hash context. 385 * @param data [IN] Input data to process. 386 * @param len [IN] Length of input data in bytes. 387 * @retval HITLS_SUCCESS Update succeeded. 388 * @retval Other Failed to update hash. 389 */ 390 int32_t HITLS_CRYPT_DigestUpdate(HITLS_HASH_Ctx *ctx, const uint8_t *data, uint32_t len); 391 392 /** 393 * @brief Finalize hash computation and get the digest. 394 * 395 * @param ctx [IN] Hash context. 396 * @param out [OUT] Buffer to store the digest. 397 * @param len [IN/OUT] IN: Buffer size, OUT: Actual digest length. 398 * @retval HITLS_SUCCESS Finalization succeeded. 399 * @retval Other Failed to finalize hash. 400 */ 401 int32_t HITLS_CRYPT_DigestFinal(HITLS_HASH_Ctx *ctx, uint8_t *out, uint32_t *len); 402 403 /** 404 * @brief Free a cipher context. 405 * 406 * @param ctx [IN] Cipher context to free. 407 */ 408 void HITLS_CRYPT_CipherFree(HITLS_Cipher_Ctx *ctx); 409 410 /** 411 * @brief Create a copy of a cryptographic key. 412 * 413 * @param key [IN] Original key to duplicate. 414 * @return New key handle copy. Returns NULL on failure. 415 */ 416 HITLS_CRYPT_Key *HITLS_CRYPT_DupKey(HITLS_CRYPT_Key *key); 417 418 /** 419 * @brief Get the public key of a cryptographic key. 420 * 421 * @param key [IN] Key to get public key from. 422 * @param pubKeyBuf [OUT] Buffer to store the public key. 423 * @param bufLen [IN] Buffer length. 424 * @param pubKeyLen [IN/OUT] IN: Buffer length, OUT: Actual public key length. 425 * @retval HITLS_SUCCESS Succeeded. 426 * @retval Other Failed. 427 */ 428 int32_t HITLS_CRYPT_GetPubKey(HITLS_CRYPT_Key *key, uint8_t *pubKeyBuf, uint32_t bufLen, uint32_t *pubKeyLen); 429 430 /** 431 * @brief KEM-Encapsulate 432 * 433 * @param libCtx [IN] Library context, used to manage cryptographic operations 434 * @param attrName [IN] Attribute name, used to configure the cryptographic algorithm 435 * @param config [IN] TLS configuration 436 * @param params [IN] KEM encapsulation parameters 437 * 438 * @retval HITLS_SUCCESS succeeded. 439 */ 440 int32_t HITLS_CRYPT_KemEncapsulate(HITLS_Lib_Ctx *libCtx, const char *attrName, 441 const HITLS_Config *config, HITLS_KemEncapsulateParams *params); 442 443 /** 444 * @brief KEM-Decapsulate 445 * 446 * @param key [IN] Key handle 447 * @param ciphertext [IN] Ciphertext data 448 * @param ciphertextLen [IN] Ciphertext data length 449 * @param sharedSecret [OUT] Shared key 450 * @param sharedSecretLen [IN/OUT] IN: Maximum length of data padding OUT: length of the shared key 451 * 452 * @retval HITLS_SUCCESS succeeded. 453 * @retval Other failure 454 */ 455 int32_t HITLS_CRYPT_KemDecapsulate(HITLS_CRYPT_Key *key, const uint8_t *ciphertext, uint32_t ciphertextLen, 456 uint8_t *sharedSecret, uint32_t *sharedSecretLen); 457 458 #ifdef __cplusplus 459 } 460 #endif 461 462 #endif /* HITLS_CRYPT_H */ 463