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_custom_extensions 18 * @ingroup hitls 19 * @brief TLS Custom Extensions 20 */ 21 22 #ifndef HITLS_CUSTOM_EXTENSIONS_H 23 #define HITLS_CUSTOM_EXTENSIONS_H 24 25 #include <stdint.h> 26 #include "hitls_type.h" 27 #include "hitls_pki_cert.h" 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /* Extension context */ 34 35 /** 36 * @ingroup hitls_custom_extensions 37 * @brief Extension is used in ClientHello messages. 38 */ 39 #define HITLS_EX_TYPE_CLIENT_HELLO 0x00001 40 41 /** 42 * @ingroup hitls_custom_extensions 43 * @brief Extension is used in Tls1.2 ServerHello messages. 44 */ 45 #define HITLS_EX_TYPE_TLS1_2_SERVER_HELLO 0x00002 46 47 /** 48 * @ingroup hitls_custom_extensions 49 * @brief Extension is used in Tls1.3 ServerHello messages. 50 */ 51 #define HITLS_EX_TYPE_TLS1_3_SERVER_HELLO 0x00004 52 53 /** 54 * @ingroup hitls_custom_extensions 55 * @brief Extension is used in HelloRetryRequest messages (TLS 1.3). 56 */ 57 #define HITLS_EX_TYPE_HELLO_RETRY_REQUEST 0x00008 58 59 /** 60 * @ingroup hitls_custom_extensions 61 * @brief Extension is used in EncryptedExtensions messages (TLS 1.3). 62 */ 63 #define HITLS_EX_TYPE_ENCRYPTED_EXTENSIONS 0x00010 64 65 /** 66 * @ingroup hitls_custom_extensions 67 * @brief Extension is used in Certificate messages. 68 */ 69 #define HITLS_EX_TYPE_TLS1_3_CERTIFICATE 0x00020 70 71 /** 72 * @ingroup hitls_custom_extensions 73 * @brief Extension is used in CertificateRequest messages. 74 */ 75 #define HITLS_EX_TYPE_TLS1_3_CERTIFICATE_REQUEST 0x00040 76 77 /** 78 * @ingroup hitls_custom_extensions 79 * @brief Extension is used in NewSessionTicket messages (TLS 1.3). 80 */ 81 #define HITLS_EX_TYPE_TLS1_3_NEW_SESSION_TICKET 0x00080 82 83 84 #define HITLS_ADD_CUSTOM_EXTENSION_RET_PACK 1 85 #define HITLS_ADD_CUSTOM_EXTENSION_RET_PASS HITLS_SUCCESS 86 87 /** 88 * @ingroup hitls_custom_extensions 89 * @brief Callback function to add a custom extension. 90 * 91 * This function is invoked when adding a custom extension to a TLS message. 92 * It prepares the extension data to be sent, utilizing certificate information if necessary. 93 * 94 * @param ctx [IN] TLS context 95 * @param extType [IN] Extension type 96 * @param context [IN] Context where the extension applies 97 * @param out [OUT] Pointer to the extension data to be sent 98 * @param outLen [OUT] Length of the extension data 99 * @param cert [IN] Pointer to the HITLS_X509_Cert structure representing certificate information 100 * @param certIndex [IN] Certificate index indicating its position in the certificate chain 101 * @param alert [OUT] Alert value provided by the user when requesting to add the custom extension 102 * @param addArg [IN] Additional argument provided when registering the callback 103 * @retval HITLS_ADD_CUSTOM_EXTENSION_RET_PACK if the extension needs to be packed, 104 * HITLS_ADD_CUSTOM_EXTENSION_RET_PASS if it does not need to be packed, 105 * otherwise, any other return value is considered a failure and will trigger a fatal alert based on the alert value. 106 */ 107 typedef int (*HITLS_AddCustomExtCallback) (const HITLS_Ctx *ctx, uint16_t extType, uint32_t context, uint8_t **out, 108 uint32_t *outLen, HITLS_X509_Cert *cert, uint32_t certIndex, uint32_t *alert, void *addArg); 109 110 111 /** 112 * @ingroup hitls_custom_extensions 113 * @brief Callback function to free a custom extension. 114 * 115 * This function is invoked to release resources allocated for a custom extension. 116 * 117 * @param ctx [IN] TLS context 118 * @param ext_type [IN] Extension type 119 * @param context [IN] Context where the extension applies 120 * @param out [IN] Extension data to be freed 121 * @param add_arg [IN] Additional argument provided when registering the callback 122 */ 123 typedef void (*HITLS_FreeCustomExtCallback) (const HITLS_Ctx *ctx, uint16_t extType, uint32_t context, 124 uint8_t *out, void *addArg); 125 126 /** 127 * @ingroup hitls_custom_extensions 128 * @brief Callback function to parse a custom extension. 129 * 130 * This function is invoked when parsing a received custom extension. It interprets the 131 * extension data and updates the TLS context based on certificate information if necessary. 132 * 133 * @param ctx [IN] TLS context 134 * @param extType [IN] Extension type 135 * @param context [IN] Context where the extension applies 136 * @param in [IN] Pointer to the received extension data 137 * @param inlen [IN] Length of the extension data 138 * @param cert [IN] Pointer to the HITLS_X509_Cert structure representing certificate information 139 * @param certIndex [IN] Certificate index indicating its position in the certificate chain 140 * @param alert [OUT] Alert value provided by the user when requesting to add the custom extension 141 * @param parseArg [IN] Additional argument provided when registering the callback 142 * @retval HITLS_SUCCESS if successful, otherwise an error code 143 */ 144 typedef int (*HITLS_ParseCustomExtCallback) (const HITLS_Ctx *ctx, uint16_t extType, uint32_t context, 145 const uint8_t **in, uint32_t *inLen, HITLS_X509_Cert *cert, uint32_t certIndex, uint32_t *alert, void *parseArg); 146 147 148 /** 149 * @ingroup hitls_custom_extensions 150 * @brief Structure to hold parameters for adding a custom extension. 151 */ 152 typedef struct { 153 uint16_t extType; /**< Extension type */ 154 uint32_t context; /**< Context where the extension applies */ 155 HITLS_AddCustomExtCallback addCb; /**< Callback function to add the extension */ 156 HITLS_FreeCustomExtCallback freeCb; /**< Callback function to free the extension */ 157 void *addArg; /**< Additional argument for add and free callbacks */ 158 HITLS_ParseCustomExtCallback parseCb; /**< Callback function to parse the extension */ 159 void *parseArg; /**< Additional argument for parse callback */ 160 } HITLS_CustomExtParams; 161 162 /** 163 * @ingroup hitls_custom_extensions 164 * @brief Add a custom extension to the TLS context using a parameter structure. 165 * 166 * This function adds a custom extension to the specified TLS context using the provided 167 * parameters encapsulated in the HITLS_CustomExtParams structure. 168 * 169 * @param ctx [IN] TLS context 170 * @param params [IN] Pointer to the structure containing custom extension parameters 171 * @retval HITLS_SUCCESS if successful 172 * For other error codes, see hitls_error.h 173 */ 174 uint32_t HITLS_AddCustomExtension(HITLS_Ctx *ctx, const HITLS_CustomExtParams *params); 175 176 /** 177 * @ingroup hitls_custom_extensions 178 * @brief Add a custom extension to the HITLS configuration using a parameter structure. 179 * 180 * This function adds a custom extension to the specified HITLS configuration using the provided 181 * parameters encapsulated in the HITLS_CustomExtParams structure. 182 * 183 * @param config [IN] Pointer to the HITLS configuration 184 * @param params [IN] Pointer to the structure containing custom extension parameters 185 * @retval HITLS_SUCCESS if successful 186 * For other error codes, see hitls_error.h 187 */ 188 uint32_t HITLS_CFG_AddCustomExtension(HITLS_Config *config, const HITLS_CustomExtParams *params); 189 190 #ifdef __cplusplus 191 } 192 #endif 193 194 #endif /* HITLS_CUSTOM_EXTENSIONS_H */ 195