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 /** 17 * @defgroup hitls_cert 18 * @ingroup hitls 19 * @brief TLS Certificate Operation Interface 20 */ 21 22 #ifndef HITLS_CERT_H 23 #define HITLS_CERT_H 24 25 #include <stdbool.h> 26 #include <stdint.h> 27 #include <stddef.h> 28 #include "hitls_type.h" 29 #include "hitls_cert_type.h" 30 #include "hitls_error.h" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * @ingroup hitls_cert 38 * @brief Set the verify store used by the TLS configuration, which is used for certificate verification. 39 * 40 * @param config [OUT] TLS link configuration. 41 * @param store [IN] CA certificate store. 42 * @param isClone [IN] Indicates whether deep copy is required. true indicates need, false indicates not need. 43 * @retval HITLS_SUCCESS, if successful. 44 * @retval For other error codes, see hitls_error.h. 45 */ 46 int32_t HITLS_CFG_SetVerifyStore(HITLS_Config *config, HITLS_CERT_Store *store, bool isClone); 47 48 /** 49 * @ingroup hitls_cert 50 * @brief Obtain the verify store used by the TLS configuration. 51 * 52 * @attention The user cannot release the memory. 53 * 54 * @param config [IN] TLS link configuration 55 * @retval Verify store 56 */ 57 HITLS_CERT_Store *HITLS_CFG_GetVerifyStore(const HITLS_Config *config); 58 59 /** 60 * @ingroup hitls_cert 61 * @brief Set the verify store used by the TLS link for certificate verification. 62 * 63 * @param ctx [OUT] TLS link object 64 * @param store [IN] CA certificate store 65 * @param isClone [IN] Indicates whether deep copy is required. The options are true and false. 66 * @retval HITLS_SUCCESS, if successful. 67 * @retval For other error codes, see hitls_error.h. 68 */ 69 int32_t HITLS_SetVerifyStore(HITLS_Ctx *ctx, HITLS_CERT_Store *store, bool isClone); 70 71 /** 72 * @ingroup hitls_cert 73 * @brief Obtain the verify store used by the TLS link. 74 * 75 * @param ctx [IN] TLS link object 76 * @retval Verify store 77 */ 78 HITLS_CERT_Store *HITLS_GetVerifyStore(const HITLS_Ctx *ctx); 79 80 /** 81 * @ingroup hitls_cert 82 * @brief Set the chain store used by the TLS configuration, which is used to construct the certificate chain. 83 * 84 * @param config [OUT] TLS link configuration 85 * @param store [IN] Certificate chain store 86 * @param isClone [IN] Indicates whether deep copy is required. The options are as follows: true: yes; false: no. 87 * @retval HITLS_SUCCESS. 88 * @retval For other error codes, see hitls_error.h. 89 */ 90 int32_t HITLS_CFG_SetChainStore(HITLS_Config *config, HITLS_CERT_Store *store, bool isClone); 91 92 /** 93 * @ingroup hitls_cert 94 * @brief Obtain the chain store used by the TLS configuration. 95 * 96 * @attention The user cannot release the memory. 97 * @param config [IN] TLS link configuration 98 * @retval Chain store 99 */ 100 HITLS_CERT_Store *HITLS_CFG_GetChainStore(const HITLS_Config *config); 101 102 /** 103 * @ingroup hitls_cert 104 * @brief Set the chain store used by the TLS link to construct the certificate chain. 105 * 106 * @param ctx [OUT] TLS link object 107 * @param store [IN] Certificate chain 108 * @param isClone [IN] Indicates whether deep copy is required. The options are true and false. 109 * @retval HITLS_SUCCESS, if successful. 110 * @retval For other error codes, see hitls_error.h. 111 */ 112 int32_t HITLS_SetChainStore(HITLS_Ctx *ctx, HITLS_CERT_Store *store, bool isClone); 113 114 /** 115 * @ingroup hitls_cert 116 * @brief Obtain the chain store used by the TLS link. 117 * 118 * @param ctx [IN] TLS object 119 * @retval Chain Store 120 */ 121 HITLS_CERT_Store *HITLS_GetChainStore(const HITLS_Ctx *ctx); 122 123 /** 124 * @ingroup hitls_cert 125 * @brief Set the cert store used by the TLS configuration. 126 * 127 * @attention If verify store is not set, use cert store to verify the certificate. 128 * If chain store is not set, use cert store to construct a certificate chain. 129 * @param config [OUT] TLS link configuration 130 * @param store [IN] Trust certificate store 131 * @param isClone [IN] Indicates whether deep copy is required. The options are true and false. 132 * @retval HITLS_SUCCESS, if successful. 133 * @retval For other error codes, see hitls_error.h. 134 */ 135 int32_t HITLS_CFG_SetCertStore(HITLS_Config *config, HITLS_CERT_Store *store, bool isClone); 136 137 /** 138 * @ingroup hitls_cert 139 * @brief Obtain the cert store used by the TLS configuration. 140 * 141 * @attention The user cannot release the memory. 142 * @param config [IN] TLS link configuration 143 * @retval Cert store 144 */ 145 HITLS_CERT_Store *HITLS_CFG_GetCertStore(const HITLS_Config *config); 146 147 /** 148 * @ingroup hitls_cert 149 * @brief Set the cert store used by the TLS link. 150 * 151 * @attention If verify store is not set, use cert store to verify the certificate. 152 * If chain store is not set, use cert store to construct a certificate chain. 153 * @param ctx [OUT] TLS link object 154 * @param store [IN] Trust certificate store 155 * @param isClone [IN] Indicates whether deep copy is required. The options are true and false. 156 * @retval HITLS_SUCCESS, if successful. 157 * @retval For other error codes, see hitls_error.h. 158 */ 159 int32_t HITLS_SetCertStore(HITLS_Ctx *ctx, HITLS_CERT_Store *store, bool isClone); 160 161 /** 162 * @ingroup hitls_cert 163 * @brief Obtain the cert store used by the TLS link. 164 * 165 * @param ctx [IN] TLS link object 166 * @retval Cert store 167 */ 168 HITLS_CERT_Store *HITLS_GetCertStore(const HITLS_Ctx *ctx); 169 170 /** 171 * @ingroup hitls_cert 172 * @brief Set the certificate verification depth. 173 * 174 * @param config [OUT] TLS link configuration 175 * @param depth [IN] Verification depth 176 * @retval HITLS_SUCCESS, if successful. 177 * @retval For other error codes, see hitls_error.h. 178 */ 179 int32_t HITLS_CFG_SetVerifyDepth(HITLS_Config *config, uint32_t depth); 180 181 /** 182 * @ingroup hitls_cert 183 * @brief Obtain the certificate verification depth. 184 * 185 * @param config [IN] TLS link configuration 186 * @param depth [OUT] Certificate verification depth 187 * @retval HITLS_SUCCESS, if successful. 188 * @retval For other error codes, see hitls_error.h. 189 */ 190 int32_t HITLS_CFG_GetVerifyDepth(const HITLS_Config *config, uint32_t *depth); 191 192 /** 193 * @ingroup hitls_cert 194 * @brief Set the certificate verification depth. 195 * 196 * @param ctx [OUT] TLS link object 197 * @param depth [IN] Verification depth 198 * @retval HITLS_SUCCESS, if successful. 199 * @retval For other error codes, see hitls_error.h. 200 */ 201 int32_t HITLS_SetVerifyDepth(HITLS_Ctx *ctx, uint32_t depth); 202 203 /** 204 * @ingroup hitls_cert 205 * @brief Obtain the certificate verification depth. 206 * 207 * @param ctx [IN] TLS link object 208 * @param depth [OUT] Certificate verification depth 209 * @retval HITLS_SUCCESS, if successful. 210 * @retval For other error codes, see hitls_error.h. 211 */ 212 int32_t HITLS_GetVerifyDepth(const HITLS_Ctx *ctx, uint32_t *depth); 213 214 /** 215 * @ingroup hitls_cert 216 * @brief Password Callback 217 * 218 * @attention This callback function must be compatible with OpenSSL and logically the same as OpenSSL. 219 * @param buf [OUT] Passwd data. 220 * @param bufLen [IN] Maximum buffer length. 221 * @param flag [IN] r/w flag. The value 0 indicates read, and the value 1 indicates write. 222 * @param userdata [IN] User data. 223 * 224 * @retval Passwd Data length 225 */ 226 typedef int32_t (*HITLS_PasswordCb)(char *buf, int32_t bufLen, int32_t flag, void *userdata); 227 228 /** 229 * @ingroup hitls_cert 230 * @brief Set the default password callback, cb can be NULL. 231 * 232 * @param config [OUT] TLS link configuration 233 * @param cb [IN] Password Callback 234 * @retval HITLS_SUCCESS, if successful. 235 * @retval For other error codes, see hitls_error.h. 236 */ 237 int32_t HITLS_CFG_SetDefaultPasswordCb(HITLS_Config *config, HITLS_PasswordCb cb); 238 239 /** 240 * @ingroup hitls_cert 241 * @brief Callback for obtaining the default password. 242 * 243 * @param config [IN] TLS link configuration. 244 * @retval Password Callback. 245 */ 246 HITLS_PasswordCb HITLS_CFG_GetDefaultPasswordCb(HITLS_Config *config); 247 248 /** 249 * @ingroup hitls_cert 250 * @brief Set the user data used by the password callback. 251 * 252 * @param config [OUT] TLS link configuration 253 * @param userdata [IN] User data 254 * @retval HITLS_SUCCESS, if successful. 255 * @retval For other error codes, see hitls_error.h. 256 */ 257 int32_t HITLS_CFG_SetDefaultPasswordCbUserdata(HITLS_Config *config, void *userdata); 258 259 /** 260 * @ingroup hitls_cert 261 * @brief Obtain the user data used by the password callback. 262 * 263 * @param config [IN] TLS link configuration 264 * @retval User Data 265 */ 266 void *HITLS_CFG_GetDefaultPasswordCbUserdata(HITLS_Config *config); 267 268 /** 269 * @ingroup hitls_cert 270 * @brief Set the default password callback, cb can be NULL 271 * 272 * @param ctx [OUT] TLS link object 273 * @param cb [IN] password Callback 274 * @retval HITLS_SUCCESS, if successful. 275 * @retval For other error codes, see hitls_error.h. 276 */ 277 int32_t HITLS_SetDefaultPasswordCb(HITLS_Ctx *ctx, HITLS_PasswordCb cb); 278 279 /** 280 * @ingroup hitls_cert 281 * @brief Callback for obtaining the default password 282 * 283 * @param ctx [IN] TLS link object 284 * @retval Password Callback 285 */ 286 HITLS_PasswordCb HITLS_GetDefaultPasswordCb(HITLS_Ctx *ctx); 287 288 /** 289 * @ingroup hitls_cert 290 * @brief Set the user data used by the default password callback. 291 * 292 * @param ctx [OUT] TLS link object 293 * @param userdata [IN] user data 294 * @retval HITLS_SUCCESS, if successful. 295 * @retval For other error codes, see hitls_error.h. 296 */ 297 int32_t HITLS_SetDefaultPasswordCbUserdata(HITLS_Ctx *ctx, void *userdata); 298 299 /** 300 * @ingroup hitls_cert 301 * @brief Obtain the user data used by the default password callback. 302 * 303 * @param ctx [IN] TLS link object 304 * @retval User data 305 */ 306 void *HITLS_GetDefaultPasswordCbUserdata(HITLS_Ctx *ctx); 307 308 /** 309 * @ingroup hitls_cert 310 * @brief Add the device certificate by the ShangMi(SM) cipher suites. 311 * Only one certificate can be added for each type. 312 * 313 * @param config [OUT] TLS link configuration 314 * @param cert [IN] Device certificate 315 * @param isClone [IN] Indicates whether deep copy is required. The options are as follows: true: yes; false: no. 316 * @param isTlcpEncCert [IN] Indicates whether the certificate is encrypted by China. 317 * The options are as follows: true: yes; false: no. 318 * @retval HITLS_SUCCESS, if successful. 319 * For details about other error codes, see hitls_error.h. 320 */ 321 int32_t HITLS_CFG_SetTlcpCertificate(HITLS_Config *config, HITLS_CERT_X509 *cert, bool isClone, bool isTlcpEncCert); 322 323 /** 324 * @ingroup hitls_cert 325 * @brief Add the private key of the device certificate by the ShangMi(SM) cipher suites. 326 * Only one private key can be added for each type of certificate. 327 * 328 * @param config [OUT] TLS link configuration 329 * @param privateKey [IN] Certificate private key 330 * @param isClone [IN] Indicates whether deep copy is required. The options are as follows: true: yes; false: no. 331 * @param isTlcpEncCertPriKey [IN] Indicates whether the private key of the encryption certificate is 332 * the private key of the encryption certificate. true: yes; false: no. 333 * @retval HITLS_SUCCESS, if successful. 334 * For details about other error codes, see hitls_error.h. 335 */ 336 int32_t HITLS_CFG_SetTlcpPrivateKey(HITLS_Config *config, HITLS_CERT_Key *privateKey, 337 bool isClone, bool isTlcpEncCertPriKey); 338 339 /** 340 * @ingroup hitls_cert 341 * @brief Add a device certificate. Only one certificate of each type can be added 342 * 343 * @param config [OUT] TLS link configuration 344 * @param cert [IN] Device certificate 345 * @param isClone [IN] Indicates whether deep copy is required. The options are as follows: true: yes; false: no. 346 * @retval HITLS_SUCCESS, if successful. 347 * @retval For other error codes, see hitls_error.h. 348 */ 349 int32_t HITLS_CFG_SetCertificate(HITLS_Config *config, HITLS_CERT_X509 *cert, bool isClone); 350 351 /** 352 * @ingroup hitls_cert 353 * @brief Load the device certificate from the file. 354 * 355 * @param config [OUT] TLS link configuration 356 * @param file [IN] File name 357 * @param type [IN] File format 358 * @retval HITLS_SUCCESS, if successful. 359 * For details about other error codes, see hitls_error.h. 360 */ 361 int32_t HITLS_CFG_LoadCertFile(HITLS_Config *config, const char *file, HITLS_ParseFormat format); 362 363 /** 364 * @ingroup hitls_cert 365 * @brief Read the device certificate from the buffer. 366 * 367 * @param config [OUT] TLS link configuration 368 * @param buf [IN] Certificate data 369 * @param bufLen [IN] Data length 370 * @param format [IN] Data format 371 * @retval HITLS_SUCCESS, if successful. 372 * @retval For other error codes, see hitls_error.h. 373 */ 374 int32_t HITLS_CFG_LoadCertBuffer(HITLS_Config *config, const uint8_t *buf, uint32_t bufLen, HITLS_ParseFormat format); 375 376 /** 377 * @ingroup hitls_cert 378 * @brief Obtain the device certificate in use. 379 * 380 * @attention The user cannot release the memory. 381 * @param config [IN] TLS link configuration 382 * @retval Device certificate 383 */ 384 HITLS_CERT_X509 *HITLS_CFG_GetCertificate(const HITLS_Config *config); 385 386 /** 387 * @ingroup hitls_cert 388 * @brief Add a device certificate. Only one certificate can be added for each type. 389 * 390 * @param ctx [OUT] TLS link object 391 * @param cert [IN] Device certificate 392 * @retval HITLS_SUCCESS, if successful. 393 * @retval For other error codes, see hitls_error.h. 394 */ 395 int32_t HITLS_SetCertificate(HITLS_Ctx *ctx, HITLS_CERT_X509 *cert, bool isClone); 396 397 /** 398 * @ingroup hitls_cert 399 * @brief Use a file to set the device certificate. 400 * 401 * @param ctx [IN/OUT] TLS connection handle 402 * @param file [IN] File name 403 * @param format [IN] Data format 404 * @retval HITLS_SUCCESS, if successful. 405 * For details about other error codes, see hitls_error.h. 406 */ 407 int32_t HITLS_LoadCertFile(HITLS_Ctx *ctx, const char *file, HITLS_ParseFormat format); 408 409 /** 410 * @ingroup hitls_cert 411 * @brief Read the device certificate from the buffer. 412 * 413 * @param ctx [OUT] TLS link object 414 * @param buf [IN] Certificate data 415 * @param bufLen [IN] Data length 416 * @param format [IN] Data format 417 * @retval HITLS_SUCCESS, if successful. 418 * @retval For other error codes, see hitls_error.h. 419 */ 420 int32_t HITLS_LoadCertBuffer(HITLS_Ctx *ctx, const uint8_t *buf, uint32_t bufLen, HITLS_ParseFormat format); 421 422 /** 423 * @ingroup hitls_cert 424 * @brief Obtain the local certificate. 425 * 426 * Returns the most recently added certificate if it is called before the certificate is selected. 427 * If no certificate is added, NULL is returned. 428 * It returns the certificate selected during the handshake if a certificate selection occurs, or NULL 429 * if no certificate is selected (e.g. on a client that does not use a client certificate). 430 * 431 * @attention: Shallow copy, can be used only during the ctx life cycle, and the caller 432 * must not release the returned pointer. 433 * @param ctx [IN] TLS link object 434 * @retval Device certificate 435 */ 436 HITLS_CERT_X509 *HITLS_GetCertificate(const HITLS_Ctx *ctx); 437 438 /** 439 * @ingroup hitls_cert 440 * @brief Obtain the peer certificate. 441 * 442 * @attention: Certificate reference increments by one. 443 * @param ctx [IN] hitls Context 444 * @retval Peer certificate 445 */ 446 HITLS_CERT_X509 *HITLS_GetPeerCertificate(const HITLS_Ctx *ctx); 447 448 /** 449 * @ingroup hitls_cert 450 * @brief Add the private key of the device certificate. 451 * Only one private key can be added for each type of certificate. 452 * 453 * @param config [OUT] TLS link configuration 454 * @param privateKey [IN] Certificate private key 455 * @param isClone [IN] Indicates whether deep copy is required. The options are as follows: true: yes; false: no. 456 * @retval HITLS_SUCCESS, if successful. 457 * @retval For other error codes, see hitls_error.h. 458 */ 459 int32_t HITLS_CFG_SetPrivateKey(HITLS_Config *config, HITLS_CERT_Key *privateKey, bool isClone); 460 461 /** 462 * @ingroup hitls_cert 463 * @brief Load the private key of the device certificate from the file. 464 * 465 * @param config [OUT] TLS link configuration 466 * @param file [IN] File name 467 * @param format [IN] Data format 468 * @retval HITLS_SUCCESS, if successful. 469 * For details about other error codes, see hitls_error.h. 470 */ 471 int32_t HITLS_CFG_LoadKeyFile(HITLS_Config *config, const char *file, HITLS_ParseFormat format); 472 473 /** 474 * @ingroup hitls_cert 475 * @brief Load the private key of the device certificate from the file, when the provider is used. 476 * 477 * @param config [OUT] TLS link configuration 478 * @param file [IN] File name 479 * @param format [IN] Data format. e.g. "PEM", "ASN1", etc. 480 * @param type [IN] Data type. e.g. "PRIKEY_RSA", "PRIKEY_ECC", "PRIKEY_PKCS8_UNENCRYPT", 481 * "PRIKEY_PKCS8_ENCRYPT", etc. 482 */ 483 int32_t HITLS_CFG_ProviderLoadKeyFile(HITLS_Config *config, const char *file, const char *format, const char *type); 484 485 /** 486 * @ingroup hitls_cert 487 * @brief Read the private key of the device certificate from the buffer. 488 * 489 * @param config [OUT] TLS link configuration 490 * @param buf [IN] Private key data 491 * @param bufLen [IN] Data length 492 * @param format [IN] Data format 493 * @retval HITLS_SUCCESS, if successful. 494 * @retval For other error codes, see hitls_error.h. 495 */ 496 int32_t HITLS_CFG_LoadKeyBuffer(HITLS_Config *config, const uint8_t *buf, uint32_t bufLen, HITLS_ParseFormat format); 497 498 /** 499 * @ingroup hitls_cert 500 * @brief Load the private key of the device certificate from the buffer, when the provider is used. 501 * 502 * @param config [OUT] TLS link configuration 503 * @param buf [IN] Private key data 504 * @param bufLen [IN] Data length 505 * @param format [IN] Data format 506 * @param type [IN] Data type 507 */ 508 int32_t HITLS_CFG_ProviderLoadKeyBuffer(HITLS_Config *config, const uint8_t *buf, uint32_t bufLen, const char *format, 509 const char *type); 510 /** 511 * @ingroup hitls_cert 512 * @brief Obtain the private key of the certificate in use. 513 * 514 * @attention The user cannot release the memory. 515 * 516 * @param config [IN] TLS link configuration 517 * @retval Certificate private key 518 */ 519 HITLS_CERT_Key *HITLS_CFG_GetPrivateKey(HITLS_Config *config); 520 521 /** 522 * @ingroup hitls_cert 523 * @brief Check whether the configured certificate matches the private key. 524 * 525 * @param config [IN] TLS link configuration 526 * @retval HITLS_SUCCESS, if successful. 527 * For details about other error codes, see hitls_error.h. 528 */ 529 int32_t HITLS_CFG_CheckPrivateKey(HITLS_Config *config); 530 531 /** 532 * @ingroup hitls_cert 533 * @brief Add the private key of the device certificate. 534 * 535 * Only one private key can be added for each type of certificate. 536 * 537 * @param ctx [OUT] TLS link object. 538 * @param pkey [IN] Device private key. 539 * @retval HITLS_SUCCESS, if successful. 540 * @retval For other error codes, see hitls_error.h. 541 */ 542 int32_t HITLS_SetPrivateKey(HITLS_Ctx *ctx, HITLS_CERT_Key *key, bool isClone); 543 544 /** 545 * @ingroup hitls_cert 546 * @brief Use the file to set the device private key. 547 * 548 * @param ctx [IN/OUT] TLS connection handle 549 * @param file [IN] File name. 550 * @param format [IN] Data format. 551 * @retval HITLS_SUCCESS, if successful. 552 * For details about other error codes, see hitls_error.h. 553 */ 554 int32_t HITLS_LoadKeyFile(HITLS_Ctx *ctx, const char *file, HITLS_ParseFormat format); 555 556 /** 557 * @ingroup hitls_cert 558 * @brief Load the private key of the device certificate from the file, when the provider is used. 559 * 560 * @param ctx [IN/OUT] TLS connection handle 561 * @param file [IN] File name. 562 * @param format [IN] Data format. 563 * @param type [IN] Data type. 564 */ 565 int32_t HITLS_ProviderLoadKeyFile(HITLS_Ctx *ctx, const char *file, const char *format, const char *type); 566 /** 567 * @ingroup hitls_cert 568 * @brief Read the private key of the device certificate from the buffer. 569 * 570 * @param ctx [OUT] TLS link object. 571 * @param buf [IN] Private key data. 572 * @param bufLen [IN] Data length. 573 * @param format [IN] Data format. 574 * @retval HITLS_SUCCESS, if successful. 575 * @retval For other error codes, see hitls_error.h. 576 */ 577 int32_t HITLS_LoadKeyBuffer(HITLS_Ctx *ctx, const uint8_t *buf, uint32_t bufLen, HITLS_ParseFormat format); 578 579 /** 580 * @ingroup hitls_cert 581 * @brief Load the private key of the device certificate from the buffer, when the provider is used. 582 * 583 * @param ctx [IN/OUT] TLS connection handle 584 * @param buf [IN] Private key data. 585 * @param bufLen [IN] Data length. 586 * @param format [IN] Data format. 587 * @param type [IN] Data type. 588 */ 589 int32_t HITLS_ProviderLoadKeyBuffer(HITLS_Ctx *ctx, const uint8_t *buf, uint32_t bufLen, const char *format, 590 const char *type); 591 /** 592 * @ingroup hitls_cert 593 * @brief Obtain the private key of the certificate in use. 594 * 595 * @attention The user cannot release the memory. 596 * 597 * @param ctx [IN] TLS link object 598 * @retval Certificate private key 599 */ 600 HITLS_CERT_Key *HITLS_GetPrivateKey(HITLS_Ctx *ctx); 601 602 /** 603 * @ingroup hitls_cert 604 * @brief Check whether the configured certificate matches the private key. 605 * 606 * @param ctx [IN] TLS link object 607 * @retval HITLS_SUCCESS, if successful. 608 * For details about other error codes, see hitls_error.h. 609 */ 610 int32_t HITLS_CheckPrivateKey(HITLS_Ctx *ctx); 611 612 /** 613 * @ingroup hitls_cert 614 * @brief Add the certificate to the certificate chain that is being used by the current config. 615 * 616 * @param config [IN] TLS link configuration 617 * @param cert [IN] Certificate to be added 618 * @param isClone [IN] Indicates whether deep copy is required. The options are true and false. 619 * @retval HITLS_SUCCESS, if successful. 620 * For details about other error codes, see hitls_error.h. 621 */ 622 int32_t HITLS_CFG_AddChainCert(HITLS_Config *config, HITLS_CERT_X509 *cert, bool isClone); 623 624 /** 625 * @ingroup hitls_cert 626 * @brief Add the certificate to the certificate store that is being used by the current config. 627 * 628 * @param config [IN] TLS link configuration 629 * @param cert [IN] Certificate to be added 630 * @param storeType [IN] Indicates which store to add cert. 631 * @param isClone [IN] Indicates whether deep copy is required. The options are true and false. 632 * @retval HITLS_SUCCESS, if successful. 633 * For details about other error codes, see hitls_error.h. 634 */ 635 int32_t HITLS_CFG_AddCertToStore(HITLS_Config *config, HITLS_CERT_X509 *cert, 636 HITLS_CERT_StoreType storeType, bool isClone); 637 638 /** 639 * @ingroup hitls_cert 640 * @brief Parse Certificate file or buffer to X509. 641 * 642 * @param config [IN] TLS link configuration 643 * @param buf [IN] Certificate file or buffer 644 * @param len [IN] bufLen 645 * @param type [IN] buf type: file or buffer 646 * @param format [IN] cert type 647 * 648 * @retval HITLS_CERT_X509 649 */ 650 HITLS_CERT_X509 *HITLS_CFG_ParseCert(HITLS_Config *config, const uint8_t *buf, uint32_t len, 651 HITLS_ParseType type, HITLS_ParseFormat format); 652 653 /** 654 * @ingroup hitls_cert 655 * @brief Parse Certificate file or buffer to X509. 656 * 657 * @param config [IN] TLS link configuration 658 * @param buf [IN] Certificate file or buffer 659 * @param len [IN] bufLen 660 * @param type [IN] buf type: file or buffer 661 * @param format [IN] cert type 662 * 663 * @retval HITLS_CERT_X509 664 */ 665 HITLS_CERT_Key *HITLS_CFG_ParseKey(HITLS_Config *config, const uint8_t *buf, uint32_t len, 666 HITLS_ParseType type, HITLS_ParseFormat format); 667 668 /** 669 * @ingroup hitls_cert 670 * @brief Parse Certificate file or buffer to X509. 671 * 672 * @param config [IN] TLS link configuration 673 * @param buf [IN] Certificate file or buffer 674 * @param len [IN] bufLen 675 * @param type [IN] buf type: file or buffer 676 * @param format [IN] cert type 677 * @param encodeType [IN] cert encode type 678 * 679 * @retval HITLS_CERT_X509 680 */ 681 HITLS_CERT_Key *HITLS_CFG_ProviderParseKey(HITLS_Config *config, const uint8_t *buf, uint32_t len, 682 HITLS_ParseType type, const char *format, const char *encodeType); 683 684 /** 685 * @ingroup hitls_cert 686 * @brief Obtain the certificate chain that is being used by the current config. 687 * @param config [IN] TLS link configuration 688 * @retval The certificate chain that is currently in use 689 */ 690 HITLS_CERT_Chain *HITLS_CFG_GetChainCerts(HITLS_Config *config); 691 692 /** 693 * @ingroup hitls_cert 694 * @brief Clear the certificate chain associated with the current certificate. 695 * 696 * @param config [IN] TLS link configuration 697 * @retval HITLS_SUCCESS, if successful. 698 * For details about other error codes, see hitls_error.h. 699 */ 700 int32_t HITLS_CFG_ClearChainCerts(HITLS_Config *config); 701 702 /** 703 * @ingroup hitls_cert 704 * @brief Clear the certificate in the current certificate. 705 * 706 * @param ctx [IN] hitls context 707 * @retval HITLS_SUCCESS, if successful. 708 * For details about other error codes, see hitls_error.h. 709 */ 710 int32_t HITLS_ClearChainCerts(HITLS_Ctx *ctx); 711 712 /** 713 * @ingroup hitls_cert 714 * @brief Release all loaded certificates and private keys. 715 * 716 * @param config [IN] TLS link configuration 717 * @retval HITLS_SUCCESS, if successful. 718 * @retval For other error codes, see hitls_error.h. 719 */ 720 int32_t HITLS_CFG_RemoveCertAndKey(HITLS_Config *config); 721 722 /** 723 * @ingroup hitls_cert 724 * @brief Release all loaded certificates and private keys. 725 * 726 * @param ctx [IN] TLS link object 727 * @retval HITLS_SUCCESS, if successful. 728 * @retval For other error codes, see hitls_error.h. 729 */ 730 int32_t HITLS_RemoveCertAndKey(HITLS_Ctx *ctx); 731 732 /** 733 * @ingroup hitls_cert 734 * @brief Certificate verification callback 735 * 736 * @attention This callback function must be compatible with OpenSSL and has the same logic as OpenSSL. 737 * @param isPreverifyOk [IN] Indicates whether the relevant certificate has passed the verification 738 * (isPreverifyOk=1) or failed (isPreverifyOk=0) 739 * @param storeCtx [IN] Cert store context 740 * @retval 1 indicates success. Other values indicate failure. 741 */ 742 typedef int (*HITLS_VerifyCb)(int32_t isPreverifyOk, HITLS_CERT_StoreCtx *storeCtx); 743 744 /** 745 * @ingroup hitls_cert 746 * @brief Set the certificate verification callback function, cb can be NULL. 747 * 748 * @param config [OUT] TLS link configuration 749 * @param callback [IN] Certificate verification callback function 750 * @retval HITLS_SUCCESS, if successful. 751 * @retval For other error codes, see hitls_error.h. 752 */ 753 int32_t HITLS_CFG_SetVerifyCb(HITLS_Config *config, HITLS_VerifyCb callback); 754 755 /** 756 * @ingroup hitls_cert 757 * @brief Obtain the certificate verification callback function. 758 * 759 * @param config [OUT] TLS link configuration 760 * @return Certificate verification callback function 761 */ 762 HITLS_VerifyCb HITLS_CFG_GetVerifyCb(HITLS_Config *config); 763 764 /** 765 * @ingroup hitls_cert 766 * @brief Set the certificate verification callback function, cb can be NULL. 767 * 768 * @param ctx [OUT] TLS link object 769 * @param callback [IN] Certificate verification callback function 770 * @retval HITLS_SUCCESS, if successful. 771 * @retval For other error codes, see hitls_error.h. 772 */ 773 int32_t HITLS_SetVerifyCb(HITLS_Ctx *ctx, HITLS_VerifyCb callback); 774 775 /** 776 * @ingroup hitls_cert 777 * @brief Obtain the certificate verification callback function. 778 * 779 * @param ctx [IN] TLS link object 780 * @retval Certificate verification callback function 781 */ 782 HITLS_VerifyCb HITLS_GetVerifyCb(HITLS_Ctx *ctx); 783 784 /** 785 * @ingroup hitls_cert 786 * @brief Set the peer certificate verification result of the current context. 787 * 788 * @param ctx [IN] TLS connection handle 789 * @param verifyResult [IN] Peer certificate verification result 790 * @retval HITLS_SUCCESS, if successful. 791 * For details about other error codes, see hitls_error.h. 792 */ 793 int32_t HITLS_SetVerifyResult(HITLS_Ctx *ctx, HITLS_ERROR verifyResult); 794 795 /** 796 * @ingroup hitls_cert 797 * @brief Return the peer certificate verification result of the current context. 798 * 799 * @param ctx [IN] TLS connection handle 800 * @param verifyResult [OUT] Peer certificate verification result 801 * @retval HITLS_SUCCESS, if successful. 802 * For details about other error codes, see hitls_error.h. 803 */ 804 int32_t HITLS_GetVerifyResult(const HITLS_Ctx *ctx, HITLS_ERROR *verifyResult); 805 806 /** 807 * @ingroup hitls_cert 808 * @brief Obtain the peer certificate chain. 809 * 810 * @param ctx [OUT] TLS connection handle 811 * @retval Peer certificate chain 812 */ 813 HITLS_CERT_Chain *HITLS_GetPeerCertChain(const HITLS_Ctx *ctx); 814 815 /** 816 * @ingroup hitls_cert 817 * @brief Obtain the trusted CA list of the peer end. 818 * 819 * @param ctx [OUT] TLS connection handle 820 * @retval Peer CA list 821 */ 822 HITLS_TrustedCAList *HITLS_GetClientCAList(const HITLS_Ctx *ctx); 823 824 /** 825 * @ingroup hitls_cert 826 * @brief Add a certificate to the attached certificate chain. 827 * 828 * @param config [OUT] Config handle 829 * @param cert [IN] X509 certificate 830 * @retval 0 indicates success. Other values indicate failure. 831 */ 832 int32_t HITLS_CFG_AddExtraChainCert(HITLS_Config *config, HITLS_CERT_X509 *cert); 833 834 /** 835 * @ingroup hitls_cert 836 * @brief Obtain the attached certificate chain. 837 * 838 * @param config [IN] Config handle 839 * @retval Attach the certificate chain. 840 */ 841 HITLS_CERT_Chain *HITLS_CFG_GetExtraChainCerts(HITLS_Config *config); 842 843 /** 844 * @ingroup hitls_cert 845 * @brief Process the certificate callback. 846 * @attention This callback function must be compatible with OpenSSL and has the same logic as OpenSSL. 847 * 848 * @param ctx [IN] TLS link object 849 * @param arg [IN] Related parameters arg 850 */ 851 typedef int32_t (*HITLS_CertCb)(HITLS_Ctx *ctx, void *arg); 852 853 /** 854 * @ingroup hitls_cert 855 * @brief Key logging callback 856 * @attention This callback function must be compatible with OpenSSL and is logically the same as OpenSSL. 857 * 858 * @param ctx [OUT] TLS Link object 859 * @param line [IN] Content to be recorded 860 */ 861 typedef void (*HITLS_KeyLogCb)(HITLS_Ctx *ctx, const char *line); 862 863 /** 864 * @ingroup hitls_cert 865 * @brief Sets the callback for recording TLS keys. 866 * @param config [OUT] TLS Link Configuration 867 * @param callback [IN] Callback function for recording keys 868 * 869 * @retval HITLS_SUCCESS, if successful. 870 * @retval For other error codes, see hitls_error.h. 871 */ 872 int32_t HITLS_CFG_SetKeyLogCb(HITLS_Config *config, HITLS_KeyLogCb callback); 873 874 /** 875 * @ingroup hitls_cert 876 * @brief Callback for obtaining TLS key logs 877 * @param config [OUT] TLS Link Configuration 878 * 879 * @retval Callback function for recording key logs 880 */ 881 HITLS_KeyLogCb HITLS_CFG_GetKeyLogCb(HITLS_Config *config); 882 883 /** 884 * @ingroup hitls_cert 885 * @brief If logging is enabled, the master key is logged 886 * 887 * @param ctx [OUT] TLS Link object. 888 * @param label [IN] Label 889 * @param secret [IN] Key 890 * @param secretLen [IN] Key length. 891 * 892 * @retval HITLS_SUCCESS, if successful. 893 * @retval For other error codes, see hitls_error.h. 894 */ 895 int32_t HITLS_LogSecret(HITLS_Ctx *ctx, const char *label, const uint8_t *secret, size_t secretLen); 896 897 #ifdef __cplusplus 898 } 899 #endif 900 901 #endif /* HITLS_CERT_H */