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 18 * @ingroup hitls 19 * @brief TLS parameter configuration 20 */ 21 22 #ifndef HITLS_H 23 #define HITLS_H 24 25 #include <stdint.h> 26 #include <stddef.h> 27 #include "hitls_type.h" 28 #include "hitls_config.h" 29 #include "hitls_cert_type.h" 30 #include "bsl_uio.h" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * @ingroup hitls 38 * @brief Create a TLS object and deep copy the HITLS_Config to the HITLS_Ctx. 39 * 40 * This is the main TLS structure, which starts to establish a secure link through the client or server 41 * on the basis that the link has been established at the network layer. 42 * 43 * @attention The HITLS_Config can be released after the creation is successful. 44 * @param config [IN] Config context 45 * @retval HITLS_Ctx pointer. If the operation fails, a null value is returned. 46 */ 47 HITLS_Ctx *HITLS_New(HITLS_Config *config); 48 49 /** 50 * @ingroup hitls 51 * @brief Release the TLS connection. 52 * 53 * @param ctx [IN] TLS connection handle. 54 * @retval void 55 */ 56 void HITLS_Free(HITLS_Ctx *ctx); 57 58 /** 59 * @ingroup hitls 60 * @brief Set the UIO object for the HiTLS context. 61 * 62 * Bind the HiTLS context to the UIO object, through which the TLS object sends data, reads data, 63 * and controls the connection status at the network layer. 64 * After successfully setting, the number of times the UIO object is referenced increases by 1. 65 * BSL_UIO_Free is called to release the association between the HiTLS and UIO when HITLS_Free is called. 66 * 67 * @attention After a HiTLS context is bound to a UIO object, the UIO object cannot be bound to other HiTLS contexts. 68 * This function must be called before HITLS_Connect and HITLS_Accept. 69 * @param ctx [OUT] TLS connection handle. 70 * @param uio [IN] UIO object. 71 * @retval HITLS_SUCCESS, if successful. 72 * @retval For other error codes, see hitls_error.h. 73 */ 74 int32_t HITLS_SetUio(HITLS_Ctx *ctx, BSL_UIO *uio); 75 76 /** 77 * @ingroup hitls 78 * @brief Read UIO for the HiTLS context. 79 * 80 * @attention Must be called before HITLS_Connect and HITLS_Accept and released after HITLS_Free. 81 * If this function has been called, you must call BSL_UIO_Free to release the UIO. 82 * @param ctx [OUT] TLS connection handle. 83 * @param uio [IN] UIO object. 84 * @retval HITLS_SUCCESS, if successful. 85 * @retval For other error codes, see hitls_error.h. 86 */ 87 int32_t HITLS_SetReadUio(HITLS_Ctx *ctx, BSL_UIO *uio); 88 89 /** 90 * @ingroup hitls 91 * @brief Obtain the UIO object from the HiTLS context. 92 * 93 * @param ctx [IN] TLS object. 94 * @retval UIO object. 95 */ 96 BSL_UIO *HITLS_GetUio(const HITLS_Ctx *ctx); 97 98 /** 99 * @ingroup hitls 100 * @brief Obtain the UIO object of the read data. 101 * 102 * @param ctx [IN] TLS object 103 * @retval UIO object 104 */ 105 BSL_UIO *HITLS_GetReadUio(const HITLS_Ctx *ctx); 106 107 /** 108 * @ingroup hitls 109 * @brief The client starts the handshake with the TLS server. 110 * 111 * Starting the handshake with the TLS server using HITLS_Connect. 112 * The UIO object must be created and bound to the HiTLS context. 113 * HITLS_Connect is designed as a non-blocking interface. If the handshake cannot be continued, 114 * the returned value will not be HITLS_SUCCESS. 115 * If the return value is HITLS_REC_NORMAL_RECV_BUF_EMPTY or HITLS_REC_NORMAL_IO_BUSY, 116 * no fatal error occurs. Problems such as network congestion or network delay may occur. 117 * You can continue to call HITLS_Connect. Note that if UIO is blocked, HITLS_Connect will also block, 118 * but the return value is processed in the same way. 119 * 120 * @attention Only clients can call this interface. 121 * @param ctx [IN] TLS connection handle. 122 * @retval HITLS_SUCCESS 123 * @retval HITLS_REC_NORMAL_RECV_BUF_EMPTY, record The receiving buffer is NULL and the handshake can be continued. 124 * @retval HITLS_REC_NORMAL_IO_BUSY, the network I/O is busy and needs to wait for the next sending. 125 * You can continue the handshake. 126 * @retval For other error codes, see hitls_error.h. 127 */ 128 int32_t HITLS_Connect(HITLS_Ctx *ctx); 129 130 /** 131 * @ingroup hitls 132 * @brief Set the initial status of the connection. 133 * 134 * @param ctx [IN] TLS connection handle. 135 * @param isClient [IN] Set the current client or server. 136 * @retval HITLS_SUCCESS, if successful. 137 * @retval For other error codes, see hitls_error.h. 138 */ 139 int32_t HITLS_SetEndPoint(HITLS_Ctx *ctx, bool isClient); 140 141 /** 142 * @ingroup hitls 143 * @brief The server waits for the client to start handshake. 144 * 145 * The server waits for the client to initiate the handshake. 146 * The UIO object must be created and bound to the HiTLS context.\n 147 * HITLS_Accept is designed for non-blocking interfaces. 148 * If the handshake cannot be continued, the system returns. The return value is not success. 149 * If the return value is HITLS_REC_NORMAL_RECV_BUF_EMPTY or HITLS_REC_NORMAL_IO_BUSY, no fatal error occurs. 150 * Problems such as network congestion or network delay may occur. You can continue to call HITLS_Accept. 151 * Note that if the UIO is blocked, the HITLS_Accept will also be blocked, but the processing 152 * of the returned value is the same. 153 * 154 * @attention Only the server calls this API. 155 * @param ctx [IN] TLS connection handle. 156 * @retval HITLS_SUCCESS, the handshake is successful. 157 * @retval HITLS_REC_NORMAL_RECV_BUF_EMPTY, record The receiving buffer is NULL and the handshake can continue. 158 * @retval HITLS_REC_NORMAL_IO_BUSY, the network I/O is busy and needs to wait for the next sending. 159 * You can continue the handshake. 160 * @retval For other error codes, see hitls_error.h. 161 */ 162 int32_t HITLS_Accept(HITLS_Ctx *ctx); 163 164 /** 165 * @ingroup hitls 166 * @brief Read application data 167 * 168 * @attention Only the application data decrypted by one record can be read by HiTLS at a time 169 * HiTLS copies the application data to the input cache. 170 * If the cache size is less than 16 KB, the maximum size of the application message decrypted 171 * by a single record is 16 KB. This will result in a partial copy of the application data 172 * You can call HITLS_GetReadPendingBytes to obtain the size of the remaining readable application data 173 * in the current record. This is useful in DTLS scenarios. 174 * @param ctx [IN] TLS context 175 * @param data [OUT] Read data 176 * @param bufSize [IN] Size of the buffer 177 * @param readLen [OUT] Read length 178 * @retval HITLS_SUCCESS, if successful 179 * @retval HITLS_REC_NORMAL_RECV_BUF_EMPTY, record The receiving buffer is NULL and can be read again. 180 * @retval HITLS_REC_NORMAL_IO_BUSY, the network I/O is busy and needs to wait for the next sending 181 * You can continue to read the I/O. 182 * @retval For other error codes, see hitls_error.h. 183 */ 184 int32_t HITLS_Read(HITLS_Ctx *ctx, uint8_t *data, uint32_t bufSize, uint32_t *readLen); 185 186 /** 187 * @ingroup hitls 188 * @brief read application data from a TLS/SSL connection 189 * @attention HITLS_Peek() is identical to HITLS_Read() except no bytes are actually 190 removed from the underlying BIO during the read 191 * @param ctx [IN] TLS context 192 * @param data [OUT] data buffer 193 * @param bufSize [IN] data buffer size 194 * @param readLen [OUT] store the number of bytes actually read in *readLen 195 * @retval HITLS_SUCCESS 196 * @retval HITLS_REC_NORMAL_RECV_BUF_EMPTY, read buffer is empty, more bytes can be read. 197 * @retval HITLS_REC_NORMAL_IO_BUSY, IO budy, waiting for next calling to read more. 198 * @retval Refer to hitls_error.h for more 199 */ 200 int32_t HITLS_Peek(HITLS_Ctx *ctx, uint8_t *data, uint32_t bufSize, uint32_t *readLen); 201 202 /** 203 * @ingroup hitls 204 * @brief Write data. 205 * 206 * Encrypts and packs data with the specified length dataLen into a single record and sends the record. 207 * 208 * @attention The length of the data to be sent cannot exceed the maximum writable length, 209 * which can be obtained by calling HITLS_GetMaxWriteSize. 210 * @param ctx [IN] TLS context 211 * @param data [IN] Data to be written 212 * @param dataLen [IN] Length to be written 213 * @param writeLen [OUT] Length of Successful Writes 214 * @retval HITLS_SUCCESS is sent successfully. 215 * @retval HITLS_REC_NORMAL_RECV_BUF_EMPTY, record If the receiving buffer is NULL, the message can be sent again. 216 * @retval HITLS_REC_NORMAL_IO_BUSY, The network I/O is busy and needs to wait for the next sending. 217 * You can continue sending the I/O. 218 * @retval For other error codes, see hitls_error.h. 219 */ 220 int32_t HITLS_Write(HITLS_Ctx *ctx, const uint8_t *data, uint32_t dataLen, uint32_t *writeLen); 221 222 /** 223 * @ingroup hitls 224 * @brief Obtain the maximum writable (plaintext) length. 225 * 226 * @param ctx [OUT] TLS connection handle. 227 * @param len [OUT] Maximum writable plaintext length (within 16 KB) 228 * @retval HITLS_SUCCESS, if successful. 229 * @retval For other error codes, see hitls_error.h. 230 */ 231 int32_t HITLS_GetMaxWriteSize(const HITLS_Ctx *ctx, uint32_t *len); 232 233 /** 234 * @ingroup hitls 235 * @brief Obtain user data from the HiTLS context. This interface is called in the callback registered with the HiTLS. 236 * 237 * @attention must be called before HITLS_Connect and HITLS_Accept. 238 * The life cycle of the user data pointer must be longer than the life cycle of the TLS object. 239 * @param ctx [OUT] TLS connection handle. 240 * @retval HITLS_SUCCESS, if successful. 241 * @retval HITLS_NULL_INPUT, the TLS object pointer of the input parameter is null. 242 */ 243 void *HITLS_GetUserData(const HITLS_Ctx *ctx); 244 245 /** 246 * @ingroup hitls 247 * @brief Save the user data in the HiTLS context, which can be obtained from the callback registered with the HiTLS. 248 * 249 * @attention must be called before HITLS_Connect and HITLS_Accept. 250 * The life cycle of the user data pointer must be greater than the life cycle of the TLS object.\n 251 * If the user data needs to be cleared, the HITLS_SetUserData(ctx, NULL) interface can be called directly. 252 * The Clean interface is not provided separately. 253 * @param ctx [OUT] TLS connection handle. 254 * @param userData [IN] Pointer to the user data. 255 * @retval HITLS_SUCCESS, if successful. 256 * @retval HITLS_NULL_INPUT, the TLS object pointer of the input parameter is null. 257 */ 258 int32_t HITLS_SetUserData(HITLS_Ctx *ctx, void *userData); 259 260 /** 261 * @ingroup hitls 262 * @brief Close the TLS connection. 263 * 264 * If the peer end is not closed, the system sends a closed notify message to the peer end. 265 * HITLS_Close must not be called if a fatal error has occurred on the link. 266 * 267 * @param ctx [IN] TLS connection handle. 268 * @retval HITLS_SUCCESS, if successful. 269 * @retval For other error codes, see hitls_error.h. 270 */ 271 int32_t HITLS_Close(HITLS_Ctx *ctx); 272 273 /** 274 * @ingroup hitls 275 * @brief Set the shutdown status of the TLS link. 276 * 277 * In HITLS_Close, if the peer end is not closed, a closed notification message is sent to the peer end. 278 * When the local end sends a closed notify message, the HiTLS sets the HITLS_SENT_SHUTDOWN flag bit. 279 * When the local end receives the closed notify message, the HiTLS sets the HITLS_RECEIVED_SHUTDOWN flag bit. 280 * By default, the HiTLS needs to send and receive closed notifications. 281 * The actual condition for properly closing a session is HITLS_SENT_SHUTDOWN. (According to the TLS RFC, 282 * it is acceptable to send only close_notify alerts without waiting for a reply from the peer.) 283 * If HITLS_RECEIVED_SHUTDOWN is set, it indicates that the peer end does not need to wait for the closed notification. 284 * 285 * @param ctx [IN] TLS connection handle. 286 * @param mode [IN] TLS shutdown status: HITLS_SENT_SHUTDOWN / HITLS_RECEIVED_SHUTDOWN. 287 * @retval HITLS_SUCCESS, if successful. 288 * @retval For other error codes, see hitls_error.h. 289 */ 290 int32_t HITLS_SetShutdownState(HITLS_Ctx *ctx, uint32_t mode); 291 292 /** 293 * @ingroup hitls 294 * @brief Obtain the shutdown status of the TLS link. 295 * 296 * @param ctx [IN] TLS connection handle. 297 * @param mode [OUT] TLS shutdown status: HITLS_SENT_SHUTDOWN / HITLS_RECEIVED_SHUTDOWN. 298 * @retval HITLS_SUCCESS, if successful. 299 * @retval For other error codes, see hitls_error.h. 300 */ 301 int32_t HITLS_GetShutdownState(const HITLS_Ctx *ctx, uint32_t *mode); 302 303 /** 304 * @ingroup hitls 305 * @brief Obtain the HiTLS negotiation version. 306 * 307 * @param ctx [IN] TLS object 308 * @param version [OUT] Negotiated version 309 * @retval HITLS_SUCCESS, obtained successfully. 310 * For details about other error codes, see hitls_error.h. 311 */ 312 int32_t HITLS_GetNegotiatedVersion(const HITLS_Ctx *ctx, uint16_t *version); 313 314 /** 315 * @ingroup hitls 316 * @brief Obtain the latest protocol version. 317 * 318 * @param ctx [IN] TLS object 319 * @param maxVersion [OUT] Latest protocol version supported 320 * @retval HITLS_SUCCESS, obtained successfully. 321 * For details about other error codes, see hitls_error.h. 322 */ 323 int32_t HITLS_GetMaxProtoVersion(const HITLS_Ctx *ctx, uint16_t *maxVersion); 324 325 /** 326 * @ingroup hitls 327 * @brief Obtain the latest protocol version. 328 * 329 * @param ctx [IN] TLS object 330 * @param maxVersion [OUT] Latest protocol version supported 331 * @retval HITLS_SUCCESS, obtained successfully. 332 * For details about other error codes, see hitls_error.h. 333 */ 334 int32_t HITLS_GetMinProtoVersion(const HITLS_Ctx *ctx, uint16_t *minVersion); 335 336 /** 337 * @ingroup hitls 338 * @brief Set the minimum protocol version based on the specified version. 339 * 340 * @param ctx [OUT] TLS object 341 * @param versiion [IN] The given version 342 * @attention The maximum version number and minimum version number must be both TLS and DTLS. Currently, 343 * only DTLS 1.2 is supported. This interface is used together with the full configuration interfaces, 344 * such as HITLS_CFG_NewDTLSConfig and HITLS_CFG_NewTLSConfig. 345 * If the TLS full configuration is configured, only the TLS version can be set. 346 * If full DTLS configuration is configured, only the DTLS version can be set. 347 * @retval HITLS_SUCCESS, if successful. 348 * @retval For other error codes, see hitls_error.h. 349 */ 350 int32_t HITLS_SetMinProtoVersion(HITLS_Ctx *ctx, uint16_t version); 351 352 /** 353 * @ingroup hitls 354 * @brief Set the maximum protocol version that is supported based on the specified version. 355 * 356 * @param ctx [OUT] TLS object 357 * @param versiion [IN] The given version 358 * @attention The maximum version number and minimum version number must be both TLS and DTLS. Currently, 359 * only DTLS 1.2 is supported. This function is used together with the full configuration interfaces, 360 * such as HITLS_CFG_NewDTLSConfig and HITLS_CFG_NewTLSConfig. 361 * If the TLS full configuration is configured, only the TLS version can be set. 362 * If full DTLS configuration is configured, only the DTLS version can be set. 363 * @retval HITLS_SUCCESS, if successful. 364 * @retval For other error codes, see hitls_error.h. 365 */ 366 int32_t HITLS_SetMaxProtoVersion(HITLS_Ctx *ctx, uint16_t version); 367 368 /** 369 * @ingroup hitls 370 * @brief Obtain whether to use the AEAD algorithm. 371 * 372 * @param ctx [IN] TLS object 373 * @param isAead [OUT] Indicates whether to use the AEAD algorithm. 374 * @retval HITLS_SUCCESS, obtained successfully. 375 * HITLS_NULL_INPUT, The input parameter pointer is null. 376 */ 377 int32_t HITLS_IsAead(const HITLS_Ctx *ctx, uint8_t *isAead); 378 379 /** 380 * @ingroup hitls 381 * @brief Check whether DTLS is used. 382 * 383 * @param ctx [IN] TLS object 384 * @param isDtls [OUT] Indicates whether to use DTLS. 385 * @retval HITLS_SUCCESS, is obtained successfully. 386 * HITLS_NULL_INPUT, The input parameter pointer is null. 387 */ 388 int32_t HITLS_IsDtls(const HITLS_Ctx *ctx, uint8_t *isDtls); 389 390 /** 391 * @ingroup hitls 392 * @brief Record the error value of the HiTLS link. 393 * 394 * @param ctx [OUT] TLS connection handle 395 * @param errorCode [IN] Error value 396 * @retval HITLS_SUCCESS, if successful. 397 * @retval For other error codes, see hitls_error.h. 398 */ 399 int32_t HITLS_SetErrorCode(HITLS_Ctx *ctx, int32_t errorCode); 400 401 /** 402 * @ingroup hitls 403 * @brief Obtain the error value of the HiTLS link. 404 * 405 * @param ctx [OUT] TLS connection handle 406 * @retval Link error value 407 */ 408 int32_t HITLS_GetErrorCode(const HITLS_Ctx *ctx); 409 410 /** 411 * @ingroup hitls 412 * @brief Obtain the information about whether the handshake is complete. 413 * 414 * @param ctx [OUT] TLS connection handle 415 * @param isDone [IN] Indicates whether the handshake is complete. 416 * @retval HITLS_SUCCESS, if successful. 417 * @retval For other error codes, see hitls_error.h. 418 */ 419 int32_t HITLS_IsHandShakeDone(const HITLS_Ctx *ctx, uint8_t *isDone); 420 421 /** 422 * @ingroup hitls 423 * @brief Indicates whether the HiTLS object functions as the server. 424 * 425 * @param ctx [OUT] TLS connection handle 426 * @param isServer [IN] Indicates whether to function as the server. 427 * @retval HITLS_SUCCESS, if successful. 428 * @retval For other error codes, see hitls_error.h. 429 */ 430 int32_t HITLS_IsServer(const HITLS_Ctx *ctx, uint8_t *isServer); 431 432 /** 433 * @ingroup hitls 434 * @brief Check the HiTLS object in the read cache. 435 * 436 * (including processed and unprocessed data, excluding the network layer) Whether there is data 437 * 438 * @param ctx [IN] TLS connection handle 439 * @param isPending [OUT] Whether there is data. The options are as follows: 1: yes; 0: no. 440 * @retval HITLS_SUCCESS, if successful. 441 * @retval For other error codes, see hitls_error.h. 442 */ 443 int32_t HITLS_ReadHasPending(const HITLS_Ctx *ctx, uint8_t *isPending); 444 445 /** 446 * @ingroup hitls 447 * @brief Obtain the number of bytes of application data to be read from the current record from the HiTLS object. 448 * 449 * @attention When the HiTLS works in data packet transmission (DTLS), the HITLS_Read may 450 * copy part of the application packet because the input buffer is not large enough. 451 * This function is used to obtain the remaining size of the application packet. 452 * This is useful for transport over DTLS. 453 * @param ctx [IN] TLS connection handle 454 * @retval Number of bytes of application data that can be read. 455 */ 456 uint32_t HITLS_GetReadPendingBytes(const HITLS_Ctx *ctx); 457 458 /** 459 * @ingroup hitls 460 * @brief Obtain the signature hash algorithm used by the peer end. 461 * 462 * @param ctx [IN] TLS connection handle 463 * @param peerSignScheme [OUT] Peer signature hash algorithm 464 * @retval HITLS_SUCCESS, if successful. 465 * @retval For other error codes, see hitls_error.h. 466 */ 467 int32_t HITLS_GetPeerSignScheme(const HITLS_Ctx *ctx, HITLS_SignHashAlgo *peerSignScheme); 468 469 /** 470 * @ingroup hitls 471 * @brief Obtain the signature hash algorithm used by the local end. 472 * 473 * @param ctx [IN] TLS connection handle 474 * @param localSignScheme [OUT] Local signature hash algorithm 475 * @retval HITLS_SUCCESS, if successful. 476 * @retval For other error codes, see hitls_error.h. 477 */ 478 int32_t HITLS_GetLocalSignScheme(const HITLS_Ctx *ctx, HITLS_SignHashAlgo *localSignScheme); 479 480 /** 481 * @ingroup hitls 482 * @brief Set the group supported by the hitls object. 483 * 484 * @param ctx [OUT] hitls context 485 * @param lst [IN] group list 486 * @param groupSize [IN] List length 487 * @retval HITLS_SUCCESS is set successfully. 488 * For details about other error codes, see hitls_error.h. 489 */ 490 int32_t HITLS_SetEcGroups(HITLS_Ctx *ctx, uint16_t *lst, uint32_t groupSize); 491 492 /** 493 * @ingroup hitls 494 * @brief Set the signature algorithm supported by the hitls object. 495 * 496 * @param ctx [OUT] hitls context. 497 * @param signAlgs [IN] List of supported signature algorithms. 498 * @param signAlgsSize [IN] Length of the signature algorithm list. 499 * @retval HITLS_SUCCESS, set successfully. 500 * For details about other error codes, see hitls_error.h. 501 */ 502 int32_t HITLS_SetSigalgsList(HITLS_Ctx *ctx, const uint16_t *signAlgs, uint16_t signAlgsSize); 503 504 /** 505 * @ingroup hitls 506 * @brief Set the EC point format of the hitls. 507 * 508 * @attention Currently, the value can only be HITLS_ECPOINTFORMAT_UNCOMPRESSED. 509 * @param ctx [OUT] hitls context. 510 * @param pointFormats [IN] ec point format, corresponding to the HITLS_ECPointFormat enumerated value. 511 * @param pointFormatsSize [IN] Length of the ec point format 512 * @retval HITLS_SUCCESS, if successful. 513 * For details about other error codes, see hitls_error.h. 514 */ 515 int32_t HITLS_SetEcPointFormats(HITLS_Ctx *ctx, const uint8_t *pointFormats, uint32_t pointFormatsSize); 516 517 /** 518 * @ingroup hitls 519 * @brief Set whether to verify the client certificate. 520 * 521 * @param ctx [OUT] TLS connection handle 522 * @param support [IN] Indicates whether to verify the client certificate, the options are 523 * as follows: true: yes; false: no. 524 * @retval HITLS_SUCCESS, if successful. 525 * @retval HITLS_NULL_INPUT, config is null. 526 */ 527 int32_t HITLS_SetClientVerifySupport(HITLS_Ctx *ctx, bool support); 528 529 /** 530 * @ingroup hitls 531 * @brief Set whether to support the function without the client certificate, Takes effect only when the client 532 * certificate is verified. 533 * 534 * Client: This setting has no impact. 535 * Server: When an NULL certificate is received from the client, indicates whether the certificate passes 536 * the verification, the verification fails by default. 537 * 538 * @param ctx [OUT] TLS connection handle 539 * @param support [IN] Indicates whether the authentication is successful when there is no client certificate. 540 true: If the certificate sent by the client is NULL, the server still passes the verification. 541 false: If the certificate sent by the client is NULL, the server fails the verification. 542 * @retval HITLS_SUCCESS, if successful. 543 * @retval HITLS_NULL_INPUT, config is null. 544 */ 545 int32_t HITLS_SetNoClientCertSupport(HITLS_Ctx *ctx, bool support); 546 547 /** 548 * @ingroup hitls 549 * @brief Set whether to support post-handshake AUTH. 550 * 551 * @param ctx [OUT] TLS connection handle 552 * @param support [IN] true: yes; false: no. 553 * @retval HITLS_SUCCESS, if successful. 554 * @retval HITLS_NULL_INPUT, config is null. 555 */ 556 int32_t HITLS_SetPostHandshakeAuthSupport(HITLS_Ctx *ctx, bool support); 557 558 /** 559 * @ingroup hitls 560 * @brief Set whether to support do not proceed dual-ended verification. 561 * 562 * @param ctx [OUT] TLS connection handle 563 * @param support [IN] true: yes; false: no. 564 * @retval HITLS_SUCCESS, if successful. 565 * @retval HITLS_NULL_INPUT, config is null. 566 */ 567 int32_t HITLS_SetVerifyNoneSupport(HITLS_Ctx *ctx, bool support); 568 569 /** 570 * @ingroup hitls 571 * @brief Set whether the client certificate can be requested only once. 572 * 573 * @param ctx [OUT] TLS connection handle 574 * @param support [IN] true: yes; false: no. 575 * @retval HITLS_SUCCESS, if successful. 576 * @retval HITLS_NULL_INPUT, config is null. 577 */ 578 int32_t HITLS_SetClientOnceVerifySupport(HITLS_Ctx *ctx, bool support); 579 580 /** 581 * @ingroup hitls 582 * @brief Obtain the value of hitlsConfig. 583 * 584 * @param ctx [IN] TLS connection handle 585 * @retval NULL, The input parameter pointer is null. 586 * @retval hitlsConfig in ctx. 587 */ 588 const HITLS_Config *HITLS_GetConfig(const HITLS_Ctx *ctx); 589 590 /** 591 * @ingroup hitls 592 * @brief Obtain the point of GlobalConfig 593 * @param ctx [IN] TLS connection handle 594 * @retval NULL The input parameter pointer is null 595 * @retval GlobalConfig in ctx 596 */ 597 HITLS_Config *HITLS_GetGlobalConfig(const HITLS_Ctx *ctx); 598 599 /** 600 * @ingroup hitls 601 * @brief Clears the configured TLS1.3 cipher suite. 602 * 603 * @param ctx [IN] TLS connection handle. 604 * @retval HITLS_SUCCESS, if successful. 605 * For details about other error codes, see hitls_error.h. 606 */ 607 int32_t HITLS_ClearTLS13CipherSuites(HITLS_Ctx *ctx); 608 609 /** 610 * @ingroup hitls 611 * @brief Set the supported cipher suites. 612 * 613 * The sequence of the cipher suites affects the priority of the selected cipher suites. 614 * The cipher suites with the highest priority are selected first. 615 * 616 * @attention Do not check the cipher suite to meet the changes in the supported version. 617 * @param ctx [OUT] TLS connection handle. 618 * @param cipherSuites [IN] Key suite array, corresponding to the HITLS_CipherSuite enumerated value. 619 * @param cipherSuitesSize [IN] Key suite array length. 620 * @retval HITLS_SUCCESS, if successful. 621 * For details about other error codes, see hitls_error.h. 622 */ 623 int32_t HITLS_SetCipherSuites(HITLS_Ctx *ctx, const uint16_t *cipherSuites, uint32_t cipherSuitesSize); 624 625 /** 626 * @ingroup hitls 627 * @brief Obtain the negotiated cipher suite pointer. 628 * 629 * @param ctx [IN] TLS connection handle 630 * @retval Pointer to the negotiated cipher suite. 631 * NULL, the input parameter pointer is null. 632 */ 633 const HITLS_Cipher *HITLS_GetCurrentCipher(const HITLS_Ctx *ctx); 634 635 /** 636 * @ingroup hitls 637 * @brief Obtain the random number of the client and server during the handshake. 638 * 639 * @param ctx [IN] TLS connection handle 640 * @param out [OUT] Random number obtained 641 * @param outlen [OUT] Length of the input parameter out. 642 * If the length is greater than the maximum random number length, the value will be changed. 643 * @param isClient [IN] True, obtain the random number of the client. 644 * False, obtain the random number of the server. 645 * @retval HITLS_SUCCESS, obtaining the status succeeded. 646 * For details about other error codes, see hitls_error.h. 647 */ 648 int32_t HITLS_GetHsRandom(const HITLS_Ctx *ctx, uint8_t *out, uint32_t *outlen, bool isClient); 649 650 /** 651 * @ingroup hitls 652 * @brief Obtain the current handshake status. 653 * 654 * @param ctx [IN] TLS connection handle 655 * @param state [OUT] Current handshake status 656 * @retval HITLS_SUCCESS, Obtaining the status succeeded. 657 * For details about other error codes, see hitls_error.h. 658 */ 659 int32_t HITLS_GetHandShakeState(const HITLS_Ctx *ctx, uint32_t *state); 660 661 /** 662 * @brief Obtain the handshake status character string. 663 * 664 * @param state [IN] Handshake status 665 * @retval Character string corresponding to the handshake status 666 */ 667 const char *HITLS_GetStateString(uint32_t state); 668 669 /** 670 * @ingroup hitls 671 * @brief Check whether a handshake is being performed. 672 * 673 * @param ctx [IN] TLS connection handle 674 * @param isHandShaking [OUT] Indicates whether the handshake is in progress. 675 * @retval HITLS_SUCCESS, Obtaining the status succeeded. 676 * For other error codes, see hitls_error.h. 677 */ 678 int32_t HITLS_IsHandShaking(const HITLS_Ctx *ctx, uint8_t *isHandShaking); 679 680 /** 681 * @ingroup hitls 682 * @brief Obtain whether renegotiation is supported. 683 * 684 * @param ctx [IN] hitls Context 685 * @param isSupportRenegotiation [OUT] Whether to support renegotiation 686 * @retval HITLS_SUCCESS, obtain successful. 687 * For details about other error codes, see hitls_error.h. 688 */ 689 int32_t HITLS_GetRenegotiationSupport(const HITLS_Ctx *ctx, uint8_t *isSupportRenegotiation); 690 691 /** 692 * @ingroup hitls 693 * @brief Check whether the handshake has not been performed. 694 * 695 * @param ctx [IN] TLS connection handle 696 * @param isBefore [OUT] Indicates whether the handshake has not been performed. 697 * @retval HITLS_SUCCESS, obtaining the status succeeded. 698 * For other error codes, see hitls_error.h. 699 */ 700 int32_t HITLS_IsBeforeHandShake(const HITLS_Ctx *ctx, uint8_t *isBefore); 701 702 /** 703 * @ingroup hitls 704 * @brief Set the MTU of a path. 705 * 706 * @param ctx [IN] TLS connection handle 707 * @param mtu [IN] Set the MTU. 708 * @retval HITLS_SUCCESS, obtaining the status succeeded. 709 * For details about other error codes, see hitls_error.h. 710 */ 711 int32_t HITLS_SetMtu(HITLS_Ctx *ctx, long mtu); 712 713 /** 714 * @ingroup hitls 715 * @brief Obtain the version number set by the client in ClientHello. 716 * 717 * @param ctx [IN] TLS connection handle 718 * @param clientVersion [OUT] Obtained version number 719 * @retval HITLS_SUCCESS, obtaining the status succeeded. 720 * For details about other error codes, see hitls_error.h. 721 */ 722 int32_t HITLS_GetClientVersion(const HITLS_Ctx *ctx, uint16_t *clientVersion); 723 724 /** 725 * @ingroup hitls 726 * @brief The client/server starts handshake. 727 * 728 * @attention In the IDLE state, the HITLS_SetEndPoint must be called first. 729 * @param ctx [IN] TLS connection handle 730 * @retval HITLS_SUCCESS, obtaining the status succeeded. 731 * For details about other error codes, see hitls_error.h. 732 */ 733 int32_t HITLS_DoHandShake(HITLS_Ctx *ctx); 734 735 /** 736 * @ingroup hitls 737 * @brief Check whether the current end is client. 738 * 739 * @param ctx [IN] TLS connection handle 740 * @param isClient [OUT] Client or not. 741 * @retval HITLS_SUCCESS, obtaining the status succeeded. 742 * For details about other error codes, see hitls_error.h. 743 */ 744 int32_t HITLS_IsClient(const HITLS_Ctx *ctx, bool *isClient); 745 746 /** 747 * @ingroup hitls 748 * @brief Set the keyupdate type of the current context and send the keyupdate message. 749 * 750 * @param ctx [IN] TLS connection handle 751 * @param updateType [IN] keyupdate type 752 * @retval HITLS_SUCCESS, if successful. 753 * For other error codes, see hitls_error.h. 754 */ 755 int32_t HITLS_KeyUpdate(HITLS_Ctx *ctx, uint32_t updateType); 756 757 /** 758 * @ingroup hitls 759 * @brief Return the keyupdate type of the current context. 760 * 761 * @param ctx [IN] TLS connection handle 762 * @retval KeyUpdateType in ctx 763 * @retval NULL, the input parameter pointer is null. 764 */ 765 int32_t HITLS_GetKeyUpdateType(HITLS_Ctx *ctx); 766 767 /** 768 * @ingroup hitls 769 * @brief Obtain the supported peer group or the number of supported peer groups of the nth match. 770 * 771 * nmatch Value range: - 1 or a positive integer 772 * This function can be called only after negotiation and can be called only by the server. 773 * If nmatch is a positive integer, check the intersection of groups on the client and server, 774 * and return the nmatch group in the intersection by groupId. 775 * If the value of nmatch is - 1, the number of intersection groups on the client and server is 776 * returned based on groupId. 777 * 778 * @param ctx [IN] TLS connection handle. 779 * @param nmatch [IN] Sequence number of the group to be obtained, -1 Return the number of supported peer groups. 780 * @param groupId [OUT] Returned result. 781 * @retval HITLS_SUCCESS, Obtaining the status succeeded. 782 * For details about other error codes, see hitls_error.h. 783 * 784 */ 785 int32_t HITLS_GetSharedGroup(const HITLS_Ctx *ctx, int32_t nmatch, uint16_t *groupId); 786 787 /** 788 * @ingroup hitls 789 * @brief Set the DTLS timeout interval callback. 790 * @param ctx [IN] TLS connection handle. 791 * @param cb [IN] DTLS obtaining timeout interval callback. 792 * @return HITLS_SUCCESS, if successful. 793 * For details about other error codes, see hitls_error.h. 794 */ 795 int32_t HITLS_SetDtlsTimerCb(HITLS_Ctx *ctx, HITLS_DtlsTimerCb cb); 796 797 798 /** 799 * @ingroup hitls 800 * @brief Obtain the supported version number. 801 * 802 * @param ctx [IN] TLS connection handle. 803 * @param version [OUT] Supported version number. 804 * @retval HITLS_SUCCESS, if successful. 805 * @retval HITLS_NULL_INPUT, config is null. 806 */ 807 int32_t HITLS_GetVersionSupport(const HITLS_Ctx *ctx, uint32_t *version); 808 809 /** 810 * @ingroup hitls 811 * @brief Set the supported version number. 812 * 813 * @param ctx [OUT] TLS connection handle 814 * @param version [IN] Supported version number. 815 * @attention The maximum version number and minimum version number must be both TLS and DTLS. Currently, 816 * only DTLS 1.2 is supported. This function is used together with the full configuration interfaces, 817 * such as HITLS_CFG_NewDTLSConfig and HITLS_CFG_NewTLSConfig. 818 * If the TLS full configuration is configured, only the TLS version can be set. If full DTLS configuration 819 * is configured, only the DTLS version can be set. 820 * The versions must be consecutive. By default, the minimum and maximum versions are supported. 821 * @retval HITLS_SUCCESS, if successful. 822 * @retval HITLS_NULL_INPUT, config is null. 823 */ 824 int32_t HITLS_SetVersionSupport(HITLS_Ctx *ctx, uint32_t version); 825 826 /** 827 * @ingroup hitls 828 * @brief Set the supported version number range. 829 * 830 * @param ctx [OUT] TLS connection handle 831 * @param minVersion [IN] Minimum version number supported. 832 * @param maxVersion [IN] Maximum version number supported. 833 * @attention The maximum version number and minimum version number must be both TLS and DTLS. 834 * Currently, only DTLS 1.2 is supported. This function is used together with the full configuration interfaces, 835 * such as HITLS_CFG_NewDTLSConfig and HITLS_CFG_NewTLSConfig. 836 * If the TLS full configuration is configured, only the TLS version can be set. If full DTLS configuration is 837 * configured, only the DTLS version can be set. 838 * @retval HITLS_SUCCESS, if successful. 839 * @retval HITLS_NULL_INPUT, config is null. 840 */ 841 int32_t HITLS_SetVersion(HITLS_Ctx *ctx, uint32_t minVersion, uint32_t maxVersion); 842 843 /** 844 * @ingroup hitls 845 * @brief Set the version number to be disabled. 846 * 847 * @param ctx [OUT] TLS connection handle 848 * @param noVersion [IN] Disabled version number. 849 * @retval HITLS_SUCCESS, if successful. 850 * @retval HITLS_NULL_INPUT, config is null. 851 */ 852 int32_t HITLS_SetVersionForbid(HITLS_Ctx *ctx, uint32_t noVersion); 853 854 /** 855 * @ingroup hitls 856 * @brief Sets whether to verify the version in the premaster secret. 857 * 858 * @param ctx [OUT] TLS Connection Handle. 859 * @param needCheck [IN] Indicates whether to perform check. 860 * @attention This parameter is valid for versions earlier than TLS1.1. 861 * true indicates that verification is supported, and false indicates that verification is not supported. In 862 * this case, rollback attacks may occur. For versions later than TLS1.1, forcible verification is supported. 863 * This interface takes effect on the server. 864 * @retval HITLS_SUCCESS, if successful. 865 * @retval HITLS_NULL_INPUT, config is null. 866 */ 867 int32_t HITLS_SetNeedCheckPmsVersion(HITLS_Ctx *ctx, bool needCheck); 868 869 /** 870 * @ingroup hitls 871 * @brief Set the silent disconnection mode. 872 * 873 * @param ctx [IN] TLS connection handle. 874 * @param mode [IN] Mode type. The value 0 indicates that the quiet disconnection mode is disabled, and the value 1 875 * indicates that the quiet disconnection mode is enabled. 876 * @retval HITLS_SUCCESS, if successful. 877 * For details about other error codes, see hitls_error.h. 878 */ 879 int32_t HITLS_SetQuietShutdown(HITLS_Ctx *ctx, int32_t mode); 880 881 /** 882 * @ingroup hitls 883 * @brief Obtain the current silent disconnection mode. 884 * 885 * @param ctx [IN] TLS connection handle 886 * @param mode [OUT] Mode type. 887 * @retval HITLS_SUCCESS, if successful. 888 * For details about other error codes, see hitls_error.h. 889 */ 890 int32_t HITLS_GetQuietShutdown(const HITLS_Ctx *ctx, int32_t *mode); 891 892 /** 893 * @ingroup hitls 894 * @brief Sets whether to support the function of automatically selecting DH parameters. 895 * 896 * If the value is true, the DH parameter is automatically selected based on the length of the certificate private key. 897 * If the value is false, the DH parameter needs to be set. 898 * 899 * @param ctx [IN/OUT] hitls context. 900 * @param support [IN] Whether to support. The options are as follows: true: yes; false: no. 901 * @retval HITLS_SUCCESS, if successful. 902 * @retval HITLS_NULL_INPUT, ctx is null. 903 */ 904 int32_t HITLS_SetDhAutoSupport(HITLS_Ctx *ctx, bool support); 905 906 /** 907 * @ingroup hitls 908 * @brief Set the DH parameter specified by the user. 909 * 910 * @param ctx [IN/OUT] hitls context. 911 * @param dhPkey [IN] User-specified DH key. 912 * @retval HITLS_SUCCESS, if successful. 913 * @retval HITLS_NULL_INPUT ctx or dhPkey field is NULL 914 */ 915 int32_t HITLS_SetTmpDh(HITLS_Ctx *ctx, HITLS_CRYPT_Key *dhPkey); 916 917 /** 918 * @ingroup hitls 919 * @brief Set the TmpDh callback function. 920 * @param ctx [IN/OUT] TLS connection handle. 921 * @param callback [IN] Set the TmpDh callback. 922 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 923 * @retval HITLS_SUCCESS, if successful. 924 */ 925 int32_t HITLS_SetTmpDhCb(HITLS_Ctx *ctx, HITLS_DhTmpCb callback); 926 927 /** 928 * @ingroup hitls 929 * @brief Sets the RecordPadding callback. 930 * 931 * @param ctx [IN/OUT] TLS Connection Handle 932 * @param callback [IN] Sets the RecordPadding callback. 933 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 934 * @retval HITLS_SUCCESS, if successful. 935 */ 936 int32_t HITLS_SetRecordPaddingCb(HITLS_Ctx *ctx, HITLS_RecordPaddingCb callback); 937 938 /** 939 * @ingroup hitls 940 * @brief Obtains the RecordPadding callback function. 941 * 942 * @param ctx [IN/OUT] TLS Connection Handle 943 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 944 * @retval HITLS_SUCCESS, if successful. 945 */ 946 HITLS_RecordPaddingCb HITLS_GetRecordPaddingCb(HITLS_Ctx *ctx); 947 948 /** 949 * @ingroup hitls 950 * @brief Sets the parameters arg required by the RecordPadding callback function. 951 * 952 * @param ctx [IN/OUT] TLS Connection Handle 953 * @param arg [IN] Related Parameter arg 954 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 955 * @retval HITLS_SUCCESS, if successful. 956 */ 957 int32_t HITLS_SetRecordPaddingCbArg(HITLS_Ctx *ctx, void *arg); 958 959 /** 960 * @ingroup hitls 961 * @brief Obtains the parameter arg required by the RecordPadding callback function. 962 * 963 * @param ctx [IN/OUT] TLS Connection Handle 964 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 965 * @retval HITLS_SUCCESS, if successful. 966 */ 967 void *HITLS_GetRecordPaddingCbArg(HITLS_Ctx *ctx); 968 969 /** 970 * @ingroup hitls 971 * @brief Obtain the verification data and length of the peer end based on the received finished message. 972 * 973 * @param ctx [IN] TLS context 974 * @param buf [OUT] verify data 975 * @param bufLen [IN] Length of the buffer to be obtained 976 * @param dataLen [OUT] Actual length of the buf 977 * @retval HITLS_SUCCESS, if successful. 978 * For details about other error codes, see hitls_error.h. 979 */ 980 int32_t HITLS_GetPeerFinishVerifyData(const HITLS_Ctx *ctx, void *buf, uint32_t bufLen, uint32_t *dataLen); 981 982 /** 983 * @ingroup hitls 984 * @brief Disables the verification of keyusage in the certificate. This function is enabled by default. 985 * 986 * @param ctx [OUT] config context 987 * @param isCheck [IN] Sets whether to check key usage. 988 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 989 * @retval HITLS_SUCCESS, if successful. 990 */ 991 int32_t HITLS_SetCheckKeyUsage(HITLS_Ctx *ctx, bool isCheck); 992 993 /** 994 * @ingroup hitls 995 * @brief Obtain the verification data and length of the local end based on the sent finished message. 996 * 997 * @param ctx [IN] TLS context 998 * @param buf [OUT] verify data 999 * @param bufLen [IN] Length of the buffer to be obtained 1000 * @param dataLen [OUT] Indicates the actual length of the buffer 1001 * @retval HITLS_SUCCESS, if successful. 1002 * For details about other error codes, see hitls_error.h. 1003 */ 1004 int32_t HITLS_GetFinishVerifyData(const HITLS_Ctx *ctx, void *buf, uint32_t bufLen, uint32_t *dataLen); 1005 1006 /** 1007 * @ingroup hitls 1008 * @brief Obtains whether security renegotiation is supported. 1009 * 1010 * @param ctx [IN] hitls context. 1011 * @param isSecureRenegotiation [OUT] Whether to support security renegotiation 1012 * @retval HITLS_SUCCESS, obtained successfully. 1013 * For details about other error codes, see hitls_error.h. 1014 */ 1015 int32_t HITLS_GetSecureRenegotiationSupport(const HITLS_Ctx *ctx, uint8_t *isSecureRenegotiation); 1016 1017 /** 1018 * @ingroup hitls 1019 * @brief Perform renegotiation. 1020 * 1021 * @attention 1. After this interface is called, the user needs to call one of the 1022 * HITLS_Connect / HITLS_Accept / HITLS_Read / HITLS_Write interfaces again, 1023 * The HITLS_Renegotiate interface is used only for setting and initialization of renegotiation, 1024 * The renegotiation process is performed when the user calls the 1025 * HITLS_Connect / HITLS_Accept / HITLS_Read / HITLS_Write. 1026 * 2. You are advised to use the HITLS_Connect / HITLS_Accept interface for renegotiation. 1027 * After the negotiation is complete, call the HITLS_Read / HITLS_Write interface. 1028 * 3. If the user uses HITLS_Read to perform renegotiation, 1029 * the user may receive the app message from the peer end during the renegotiation. 1030 * (1) If the renegotiation has not started, the HiTLS will return the message to the user. 1031 * (2) If the renegotiation is in progress, no app message is received in this scenario, 1032 * and the HiTLS sends an alert message to disconnect the link. 1033 * 4. If the user uses the HITLS_Connect / HITLS_Accept / HITLS_Write for renegotiation, 1034 * the user may receive the app message from the peer end during the renegotiation, 1035 * HiTLS caches the message, the message is returned when a user calls HITLS_Read. 1036 * Maximum of 50 app messages can be cached, if the cache is full, subsequent app messages will be 1037 * ignored. 1038 * 5. In the DTLS over UDP scenario, if the user functions as the server, 1039 * packet loss occurs in the renegotiation request(hello request). 1040 * (1) If the user calls the HITLS_Write for renegotiation, the app message to be sent is 1041 * sent to the peer end after packet loss occurs in the renegotiation request. 1042 * (2) The HiTLS does not retransmit the renegotiation request. The user needs to call the 1043 * HITLS_Renegotiate and HITLS_Accept interfaces again to continue the renegotiation. 1044 * You can call the HITLS_GetRenegotiationState interface to determine 1045 * whether the current renegotiation is in the renegotiation state, 1046 * If the renegotiation is not in the renegotiation state, 1047 * call the HITLS_Renegotiate and HITLS_Accept interfaces again to continue the renegotiation. 1048 * 6. In the DTLS over UDP scenario, if the user as the client, 1049 * packet loss occurs in the renegotiation request (client hello). 1050 * (1) If the user calls the HITLS_Write to perform renegotiation, the app message is not 1051 * sent to the peer end after packet loss occurs in the renegotiation request. 1052 * Instead, the user waits for the response from the peer end. 1053 * (2) The client hello message is retransmitted inside the HiTLS, 1054 * and the user does not need to initiate renegotiation again. 1055 * @param ctx [IN] TLS Connection Handle 1056 * 1057 * @retval HITLS_SUCCESS, if successful. 1058 * @retval For details about other error codes, see hitls_error.h. 1059 */ 1060 int32_t HITLS_Renegotiate(HITLS_Ctx *ctx); 1061 1062 /** 1063 * @ingroup hitls 1064 * @brief Obtain the current is whether in the renegotiation state. 1065 * 1066 * @attention For the server, the server does not enter the renegotiation state by sending only the hello request 1067 * message, The server enters the renegotiation state only after receiving the client hello message. 1068 * 1069 * @param ctx [IN] TLS Connection Handle. 1070 * @param isRenegotiationState [OUT] Indicates whether the renegotiation is in the renegotiation state. 1071 * true: in the renegotiation state; false: not in the renegotiation state. 1072 * 1073 * @retval HITLS_SUCCESS, if successful. 1074 * @retval For details about other error codes, see hitls_error.h. 1075 */ 1076 int32_t HITLS_GetRenegotiationState(const HITLS_Ctx *ctx, uint8_t *isRenegotiationState); 1077 1078 1079 /** 1080 * @ingroup hitls 1081 * @brief Obtain the current internal status. 1082 * 1083 * @param ctx [IN] TLS connection Handle. 1084 * @param rwState [OUT] Current internal status information. 1085 * @retval HITLS_SUCCESS, if successful. 1086 * @retval For details about other error codes, see hitls_error.h. 1087 */ 1088 int32_t HITLS_GetRwstate(const HITLS_Ctx *ctx, uint8_t *rwstate); 1089 1090 /** 1091 * @ingroup hitls 1092 * @brief Check whether the client certificate can be verified. 1093 * 1094 * @param ctx [IN] TLS connection Handle. 1095 * @param isSupport [OUT] Indicates whether to verify the client certificate. 1096 * @retval HITLS_SUCCESS, if successful. 1097 * @retval HITLS_NULL_INPUT, ctx is null. 1098 */ 1099 int32_t HITLS_GetClientVerifySupport(HITLS_Ctx *ctx, uint8_t *isSupport); 1100 1101 /** 1102 * @ingroup hitls 1103 * @brief Check whether no client certificate is supported, This command is valid only when client certificate 1104 * verification is enabled. 1105 * 1106 * @param ctx [IN] TLS Connection Handle. 1107 * @param isSupport [OUT] Whether no client certificate is supported. 1108 * @retval HITLS_SUCCESS, if successful. 1109 * @retval HITLS_NULL_INPUT, ctx is null. 1110 */ 1111 int32_t HITLS_GetNoClientCertSupport(HITLS_Ctx *ctx, uint8_t *isSupport); 1112 1113 /** 1114 * @ingroup hitls 1115 * @brief Query whether post-handshake AUTH is supported 1116 * 1117 * @param ctx [IN] TLS connection Handle. 1118 * @param isSupport [OUT] indicates whether to support post-handshake AUTH. 1119 * @retval HITLS_SUCCESS, if successful. 1120 * @retval HITLS_NULL_INPUT, ctx is null. 1121 */ 1122 int32_t HITLS_GetPostHandshakeAuthSupport(HITLS_Ctx *ctx, uint8_t *isSupport); 1123 1124 /** 1125 * @ingroup hitls 1126 * @brief Query if support is available for not performing dual-end verification. 1127 * 1128 * @param ctx [IN] TLS Connection Handle. 1129 * @param isSupport [OUT] if support is available for not performing dual-end verification. 1130 * @retval HITLS_SUCCESS, if successful. 1131 * @retval HITLS_NULL_INPUT, ctx is null. 1132 */ 1133 int32_t HITLS_GetVerifyNoneSupport(HITLS_Ctx *ctx, uint8_t *isSupport); 1134 1135 /** 1136 * @ingroup hitls 1137 * @brief Query whether the client certificate can be requested only once. 1138 * 1139 * @param ctx [IN] TLS Connection Handle. 1140 * @param isSupport [OUT] Indicates whether the client certificate can be requested only once. 1141 * @retval HITLS_SUCCESS, if successful. 1142 * @retval HITLS_NULL_INPUT, ctx is null. 1143 */ 1144 int32_t HITLS_GetClientOnceVerifySupport(HITLS_Ctx *ctx, uint8_t *isSupport); 1145 1146 1147 /** 1148 * @ingroup hitls 1149 * @brief Clears the renegotiation count. 1150 * 1151 * @param ctx [IN] hitls context. 1152 * @param renegotiationNum [OUT] Number of incoming renegotiations. 1153 * @retval HITLS_SUCCESS, if successful. 1154 * For details about other error codes, see hitls_error.h. 1155 */ 1156 int32_t HITLS_ClearRenegotiationNum(HITLS_Ctx *ctx, uint32_t *renegotiationNum); 1157 1158 /** 1159 * @ingroup hitls 1160 * @brief Obtain the negotiated group information. 1161 * 1162 * @param ctx [IN] TLS Connection Handle. 1163 * @param group [OUT] Negotiated group information. 1164 * @retval HITLS_SUCCESS, if successful. 1165 * @retval HITLS_NULL_INPUT, ctx is null. 1166 */ 1167 int32_t HITLS_GetNegotiateGroup(const HITLS_Ctx *ctx, uint16_t *group); 1168 1169 /** 1170 * @ingroup hitls 1171 * @brief Set the function to support the specified feature. 1172 * 1173 * @param ctx [OUT] TLS Connection Handle 1174 * @param mode [IN] Mode features to enabled. 1175 * @retval HITLS_NULL_INPUT, the input parameter pointer is null. 1176 * @retval HITLS_SUCCESS, if successful. 1177 */ 1178 int32_t HITLS_SetModeSupport(HITLS_Ctx *ctx, uint32_t mode); 1179 1180 /** 1181 * @ingroup hitls 1182 * @brief Obtain the mode of the function feature in the config file. 1183 * 1184 * @param ctx [OUT] TLS Connection Handle 1185 * @param mode [OUT] Mode obtain the output parameters of the mode. 1186 * @retval HITLS_NULL_INPUT, the input parameter pointer is null. 1187 * @retval HITLS_SUCCESS, if successful. 1188 */ 1189 int32_t HITLS_GetModeSupport(const HITLS_Ctx *ctx, uint32_t *mode); 1190 1191 /** 1192 * @ingroup hitls 1193 * @brief Setting the Encrypt-Then-Mac mode. 1194 * 1195 * @param ctx [IN] TLS connection handle. 1196 * @param encryptThenMacType [IN] Current Encrypt-Then-Mac mode. 1197 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1198 * @retval HITLS_SUCCESS, if successful. 1199 */ 1200 int32_t HITLS_SetEncryptThenMac(HITLS_Ctx *ctx, uint32_t encryptThenMacType); 1201 1202 /** 1203 * @ingroup hitls 1204 * @brief Obtains the Encrypt-Then-Mac type 1205 * 1206 * @param ctx [IN] TLS connection Handle. 1207 * @param encryptThenMacType [OUT] Current Encrypt-Then-Mac mode. 1208 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1209 * @retval HITLS_SUCCESS, if successful. 1210 */ 1211 int32_t HITLS_GetEncryptThenMac(const HITLS_Ctx *ctx, uint32_t *encryptThenMacType); 1212 1213 /** 1214 * @ingroup hitls 1215 * @brief Setting the value of server_name. 1216 * 1217 * @param ctx [IN] TLS connection handle. 1218 * @param serverName [IN] serverName. 1219 * @param serverNameStrlen [IN] serverName length. 1220 * @retval HITLS_SUCCESS, if successful. 1221 * For details about other error codes, see hitls_error.h. 1222 */ 1223 int32_t HITLS_SetServerName(HITLS_Ctx *ctx, uint8_t *serverName, uint32_t serverNameStrlen); 1224 1225 /** 1226 * @ingroup hitls 1227 * @brief The algorithm suite can be preferentially selected from the algorithm list supported by the server. 1228 * 1229 * @param ctx [IN] TLS Connection Handle. 1230 * @param isSupport [IN] Support or Not. 1231 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1232 * @retval HITLS_SUCCESS, if successful. 1233 */ 1234 int32_t HITLS_SetCipherServerPreference(HITLS_Ctx *ctx, bool isSupport); 1235 1236 /** 1237 * @ingroup hitls 1238 * @brief Obtains whether the current cipher suite supports preferential selection 1239 * from the list of algorithms supported by the server. 1240 * 1241 * @param ctx [IN] TLS connection handle. 1242 * @param isSupport [OUT] Support or Not. 1243 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1244 * @retval HITLS_SUCCESS, if successful. 1245 */ 1246 int32_t HITLS_GetCipherServerPreference(const HITLS_Ctx *ctx, bool *isSupport); 1247 1248 /** 1249 * @ingroup hitls 1250 * @brief Sets whether to support renegotiation. 1251 * 1252 * @param ctx [IN/OUT] TLS connection handle. 1253 * @param isSupport [IN] Support or Not, true: yes; false: no. 1254 * @retval HITLS_SUCCESS, if successful. 1255 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1256 */ 1257 int32_t HITLS_SetRenegotiationSupport(HITLS_Ctx *ctx, bool isSupport); 1258 1259 /** 1260 * @ingroup hitls 1261 * @brief Set whether to allow a renegotiate request from the client 1262 * @param ctx [IN/OUT] TLS connection handle. 1263 * @param isSupport [IN] Support or Not, true: yes; false: no. 1264 * @retval HITLS_SUCCESS, if successful. 1265 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1266 */ 1267 int32_t HITLS_SetClientRenegotiateSupport(HITLS_Ctx *ctx, bool isSupport); 1268 1269 /** 1270 * @ingroup hitls 1271 * @brief Set whether to abort handshake when server doesn't support SecRenegotiation 1272 * @param ctx [IN/OUT] TLS connection handle. 1273 * @param isSupport [IN] Support or Not, true: yes; false: no. 1274 * @retval HITLS_SUCCESS, if successful. 1275 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1276 */ 1277 int32_t HITLS_SetLegacyRenegotiateSupport(HITLS_Ctx *ctx, bool isSupport); 1278 1279 /** 1280 * @ingroup hitls 1281 * @brief Sets whether to support session tickets. 1282 * 1283 * @param ctx [IN/OUT] TLS connection handle. 1284 * @param isSupport [IN] whether to support session tickets, true: yes; false: no 1285 * @retval HITLS_SUCCESS, if successful. 1286 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1287 */ 1288 int32_t HITLS_SetSessionTicketSupport(HITLS_Ctx *ctx, bool isSupport); 1289 1290 /** 1291 * @ingroup hitls 1292 * @brief Check whether the session ticket is supported. 1293 * 1294 * @param ctx [IN] TLS connection handle. 1295 * @param isSupport [OUT] whether to support session tickets, true: yes; false: no 1296 * @retval HITLS_SUCCESS, if successful. 1297 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1298 */ 1299 int32_t HITLS_GetSessionTicketSupport(const HITLS_Ctx *ctx, uint8_t *isSupport); 1300 1301 /** 1302 * @ingroup hitls 1303 * @brief Sets whether to perform cookie exchange in the dtls. 1304 * 1305 * @param ctx [IN] TLS connection handle. 1306 * @param isSupport [IN] Indicates whether to perform cookie exchange 1307 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1308 * @retval HITLS_SUCCESS, if successful. 1309 */ 1310 int32_t HITLS_SetDtlsCookieExangeSupport(HITLS_Ctx *ctx, bool isSupport); 1311 1312 /** 1313 * @ingroup hitls 1314 * @brief Querying whether the DTLS performs cookie exchange. 1315 * 1316 * @param ctx [IN] TLS connection handle. 1317 * @param isSupport [IN] Indicates whether to perform cookie exchange. 1318 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1319 * @retval HITLS_SUCCESS, if successful. 1320 */ 1321 int32_t HITLS_GetDtlsCookieExangeSupport(const HITLS_Ctx *ctx, bool *isSupport); 1322 1323 /** 1324 * @ingroup hitls 1325 * @brief Sets whether to send handshake messages by flight distance. 1326 * 1327 * @param ctx [IN/OUT] TLS connection handle. 1328 * @param isEnable [IN] Indicates whether to enable handshake information sending by flight distance. 1329 * The value 0 indicates disable, other values indicate enable. 1330 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1331 * @retval HITLS_SUCCESS, if successful. 1332 */ 1333 int32_t HITLS_SetFlightTransmitSwitch(HITLS_Ctx *ctx, uint8_t isEnable); 1334 1335 /** 1336 * @ingroup hitls 1337 * @brief Obtains the status of whether to send handshake information according to the flight distance. 1338 * 1339 * @param ctx [IN] TLS connection handle. 1340 * @param isEnable [OUT] Indicates whether to send handshake information by flight distance 1341 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1342 * @retval HITLS_SUCCESS, if successful. 1343 */ 1344 int32_t HITLS_GetFlightTransmitSwitch(const HITLS_Ctx *ctx, uint8_t *isEnable); 1345 1346 /** 1347 * @ingroup hitls 1348 * @brief set the max empty records number can be received 1349 * 1350 * @param ctx [IN/OUT] TLS connection handle. 1351 * @param emptyNum [IN] Indicates the max number of empty records can be received 1352 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1353 * @retval HITLS_SUCCESS, if successful. 1354 */ 1355 int32_t HITLS_SetEmptyRecordsNum(HITLS_Ctx *ctx, uint32_t emptyNum); 1356 1357 /** 1358 * @ingroup hitls 1359 * @brief Obtain the max empty records number can be received 1360 * 1361 * @param ctx [IN] TLS connection handle. 1362 * @param emptyNum [OUT] Indicates the max number of empty records can be received 1363 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1364 * @retval HITLS_SUCCESS, if successful. 1365 */ 1366 int32_t HITLS_GetEmptyRecordsNum(const HITLS_Ctx *ctx, uint32_t *emptyNum); 1367 1368 /** 1369 * @ingroup hitls 1370 * @brief Sets the maximum size of the certificate chain that can be sent from the peer end. 1371 * 1372 * @param ctx [IN/OUT] TLS connection handle. 1373 * @param maxSize [IN] Sets the maximum size of the certificate chain that can be sent from the peer end. 1374 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1375 * @retval HITLS_SUCCESS, if successful. 1376 */ 1377 int32_t HITLS_SetMaxCertList(HITLS_Ctx *ctx, uint32_t maxSize); 1378 1379 /** 1380 * @ingroup hitls 1381 * @brief Obtains the maximum size of the certificate chain that can be sent by the peer end. 1382 * 1383 * @param ctx [IN] TLS connection handle. 1384 * @param maxSize [OUT] Maximum size of the certificate chain that can be sent from the peer end. 1385 * @retval HITLS_NULL_INPUT, the input parameter pointer is NULL. 1386 * @retval HITLS_SUCCESS, if successful. 1387 */ 1388 int32_t HITLS_GetMaxCertList(const HITLS_Ctx *ctx, uint32_t *maxSize); 1389 1390 /** 1391 * @ingroup hitls 1392 * @brief This interface is valid only on the server. When the post-handshake command is configured, 1393 * the client identity is verified through this interface. 1394 * 1395 * @param ctx [IN] TLS Connection Handle 1396 * @retval HITLS_INVALID_INPUT, invalid input parameter. 1397 * @retval HITLS_SUCCESS, if successful. 1398 * @retval For details about other error codes, see hitls_error.h. 1399 */ 1400 int32_t HITLS_VerifyClientPostHandshake(HITLS_Ctx *ctx); 1401 #ifdef __cplusplus 1402 } 1403 #endif 1404 1405 #endif /* HITLS_H */ 1406